This chapter covers VintagestoryLib.dll, the game’s engine: the client (ClientMain, the screens, the renderer, the
OpenGL platform), the server (ServerMain and its systems), and the code both share (mod loading, assets, networking,
chunks, inventories). It is closed source and not part of the modding API, so nothing in it is promised to stay the
same between versions. It is for mod developers who Harmony-patch the engine (prefixes, postfixes and transpilers),
who reach into it by reflection, or who call its public types directly, for example by casting api.World to
ClientMain or ServerMain.
Other chapters cover the public API (VintagestoryAPI), the base game mods (VSEssentials, VSSurvivalMod,
VSCreativeMod), content (JSON assets), shaders and the bundled libraries. Many engine changes here are the
implementation of an API change; where that is so, this chapter describes the engine side and says “see the API
chapter” for the rest.
How it was made: the engine of both versions was decompiled with the same decompiler and the same settings, so every
difference between the two decompiles is a real change in the code, not decompiler noise. The decompiles were compared
file by file, and a member-level list was made from the compiled metadata of both assemblies, private members
included. Everything here was checked against the decompiled code; points that are inference rather than something
read directly in the code are marked “(inferred)”. Short decompiled snippets are quoted where they show a changed
patch point; you will need your own decompile for anything longer.
1.23.0-pre.1 is a pre-release. Anything here can change again before 1.23.0, and engine internals change more freely
than the API. Re-check your patches against each new pre-release.
14 / 14 (two of each are compiler-generated helpers)
Types added / removed / changed
27 / 11 / 11
Members added / removed / changed
534 / 164 / 131
Of the removed members, reachable without reflection
88
Types that became internal
6 (the master-server packet types)
The engine no longer references ICSharpCode.SharpZipLib (mod zips are read with System.IO.Compression), embeds a
JSON schema for dialogue assets, and reports its version as 1.23.0-pre.1 (assembly version 1.23.0.0). The network
protocol version went from 1.22.6 to 1.23.2, so 1.22 and 1.23 clients and servers cannot play together.
These follow from the shape of the diff and apply to almost every patch.
Target patches by full signature. Many methods gained overloads beside the old ones: FastBlockPos overloads
on the block accessors, WorldMap, ClientWorldMap and ServerWorldMap; ClientEventManager.TriggerChunkRetesselated(Vec3i, int);
TextureAtlasManager.InsertTextureOrAddReference; ServerMain.SendPacket(ConnectedClient, ...). A
[HarmonyPatch(typeof(X), "Name")] without argument types that worked in 1.22.7 can now be ambiguous, and a patch
on the old overload may no longer see the engine’s own calls, which moved to the new one.
Transpilers that count locals or match calls will drift. Several kinds of change move IL without changing
behaviour:
the HiDPI work replaced window.ClientSize and Platform.WindowSize with FramebufferSize in dozens of methods
(same call count, different getter);
methods gained locals (ClientPlatformWindows.SetupDefaultFrameBuffers, ChunkRenderer.RenderOpaque,
SystemRenderEntities.OnRenderOpaque3D, GameMain.RayTraceForSelection) or lost them (ScreenManager.Render);
string.Format and Path.Combine argument buffers now use the runtime’s
System.Runtime.CompilerServices.InlineArrayN<T> instead of compiler-generated <>y__InlineArrayN<T> types,
which changes generic type tokens in many methods (a newer compiler, inferred);
binary reads moved from MemoryStream plus BinaryReader to the API’s BinarySpanReader, removing locals and
using blocks;
version strings ("1.22.7" to "1.23.0-pre.1") are literals in many methods.
Value types and spans.NetIncomingMessage became a struct, SpawnOppurtunity became the struct
SpawnOpportunity, and the master-server packets became internal structs. A prefix that takes a struct must take it
by ref to change it. ServerMain’s broadcast methods take params ReadOnlySpan<IServerPlayer>; a patch must
declare the parameter with that type, and span parameters cannot be boxed into __args (inferred).
Fields that became properties.Camera.Fov, Asset.FilePath and WorldChunk.BlockEntities changed from
fields to properties. A mod compiled against 1.22.7 that touches them fails with MissingFieldException until it is
rebuilt, and GetField reflection returns null.
Primary constructors.ClientPlayerInventoryManager and ServerPlayerInventoryManager now use primary
constructors, so their private game and server fields are gone; the captured values live in compiler-generated
fields (<game>P, <server>P).
Renamed parameters. Harmony injects arguments by name, so a renamed parameter breaks a patch that names it:
TextureAtlasManager.GetOrInsertTexture (loc to path), BleedingJsonTesselator.TryGetCustomTexture
(result to cTexResult), APIBase.LoadModConfig and friends (filename to fileName),
ServerMain.HandleChatMessage (groupid to groupId), ServerPlayer.Disconnect (message to logMessage).
Async rewrites. Several methods became async (GuiScreenDownloadMods.installAsync,
GuiScreenGetUpdate.downloadInstallerAsync, ServerConnectData.FromHostAsync, ServerSystemHeartbeat.SendRequestAsync).
Their bodies live in compiler-generated state machines; patch the state machine’s MoveNext or, better, patch
something else.
Rebuild against 1.23. Constants such as GameVersion.NetworkVersion and the generated packet field ids are
inlined into your assembly when you compile it. A mod built against 1.22.7 keeps the old values.
Window size and framebuffer size are separate (HiDPI, Wayland).ClientMain.Width/Height and IRenderAPI.FrameWidth/FrameHeight are now framebuffer pixels, with new WindowWidth/WindowHeight; RuntimeEnv.GUIScale now includes the display scale; every viewport and framebuffer uses FramebufferSize; mouse positions are scaled on macOS and Wayland.
Transpilers on ClientSize/WindowSize reads (rendering, screens, screenshots); GUI or overlay code that divides by ClientSettings.GUIScale or converts FrameWidth to pixels itself. Platform and window
2
WorldChunk.BlockEntities is keyed by in-chunk index. It went from a public Dictionary<BlockPos, BlockEntity> field to a lazily created Dictionary<int, BlockEntity> property keyed by pos.ToIndex3d().
Anything that indexes or iterates a chunk’s block entities; compiled mods fail with MissingFieldException. Block accessors and chunk data
3
Mod loading changed.ModContainer’s constructor is private (use CreateIfSourceTypeIsUnderstood); ModLoader.LoadMods and ModCompilationContext take an EnumAppSide; wrong-side mods, content-only ones included, are now disabled before they are unpacked; source mods are parsed, not compiled, to read their mod info; SharpZipLib is gone.
Mod managers, loaders and patches on mod discovery; content mods marked "side": "Server"; source mods that relied on [ModDependency]. Mods
4
The network transport and the server’s send paths were rewritten.NetIncomingMessage is a struct, ReadMessage() became TryReadMessage(out ...), INetworkConnection uses spans, ServerNetManager is gone, a ConnectedClient is made only on the first login packet, broadcasts take params ReadOnlySpan<IServerPlayer> and send by ConnectedClient. Raw byte[] sends to remote clients appear to disconnect them in pre.1 (inferred).
Network patches, proxies and bots; mods that pass a null in a broadcast skip list, use a custom IServerPlayer, or send raw byte arrays. Networking
5
The world has a separate worldgen seed.SaveGame.SeedWorldgen drives terrain; Seed (and World.Seed) is random for new worlds and re-randomised once for 1.22 worlds; clients never receive the terrain seed.
Worldgen code and terrain tools that read World.Seed, WorldManager.Seed or SaveGame.Seed. The worldgen seed
6
Hotbar slot numbers. The skill slot is active slot -1 and the off-hand -2; slots 10 and up are always backpack slots; the off-hand hunger penalty uses the key offhandpenalty.
Code that uses 10 for the skill slot or shifts backpack slots by one; HUD patches. Player inventories
7
Recipe registries became custom registries.GameMain.GetRecipeRegistry returns CustomRegistryBase and is obsolete; ClassRegistry’s recipe-registry members were renamed.
Mods that register or look up recipe registries through the engine types. Registries
8
Anti-abuse is on by default, and bans are by UID.ServerConfig.AntiAbuse defaults to Auto (public dedicated servers run at Basic), placements count, the range slack fell to 0.25 and pickingrange no longer exempts; PlayerDataManager keeps bans and the whitelist in UID dictionaries and lost GetPlayerBan/GetPlayerWhitelist.
Server admin mods, mods that place or break blocks for players, mods that read ban lists. Anti-abuse
9
Spawner hooks moved.OnTrySpawnEntity now runs on the spawner thread per candidate position; OnTrySpawnGroupNearOffthread is gone (use OnEntityGroupSpawning); SpawnOppurtunity is the struct SpawnOpportunity.
Rendering patch points moved. OIT textures now live in the transparent framebuffer (static ids removed), the selection outline and debug wireframes draw at AfterOIT, SetupDefaultFrameBuffers gained a local, JsonTesselator was rewritten (public decor helpers gone; a missing atlas pool now skips the block), tesselations carry ids, and atlas textures can be freed at run time.
Renderer mods, shader-pipeline patches, chunk-mesh transpilers, atlas readers. Rendering systems
11
Joining and sounds in ScreenManager.ConnectToMultiplayer(string, string) is internal and takes a Task<ServerConnectData>; ServerConnectData.FromHost became FromHostAsync; PlaySound(string) and PlaySound(AssetLocation) need a bool randomizePitch.
Both packet handler overloads are called. For block entities and entities, client and server, the engine calls the new SerializedData overload and then the old byte[] one.
Three things run through this whole area. First, the engine now keeps the window’s logical size and its
framebuffer’s pixel size apart (HiDPI and Wayland support): every screen, ElementWindowBounds, the main menu
background and ScreenManager.Render(float) read Platform.FramebufferSize where they read Platform.WindowSize,
and every layout that divided by ClientSettings.GUIScale now divides by RuntimeEnv.GUIScale, which is set to
ClientSettings.GUIScale * RuntimeEnv.DPIHScale (in the MainMenuAPI constructor and in the guiScale settings
watcher). On a display with a DPI scale of 1 the numbers are the same (inferred); on a scaled display a mod screen that
still uses WindowSize or ClientSettings.GUIScale lays out at the wrong size. ClientPlatformAbstract.FramebufferSize
and the platform side are covered under “Platform and window”. Second, ScreenManager now calls GuiScreen.OnScreenUnload()
(which existed in 1.22.7 but was never called) on every screen it leaves, and routes StartMainMenu and StartGame
through LoadScreen. Third, many methods compare against the version literal, which changed from "1.22.7" to
"1.23.0-pre.1" (ldstr): a transpiler that matches the old literal no longer finds it.
DoGameInitStage1() (run on its own thread from ScreenManager.Start) now sets loadingText and logs “Loading assets”
before it asks SessionManager.GetNewestVersion for the newest version; GetNewestVersion now fetches
latestunstable.txt over HTTPS instead of lateststable.txt. More important, GuiScreenLoadingGame.RenderToDefaultFramebuffer
no longer waits for ScreenManager.loadingText to become null (the end of stage 1) before it calls
DoGameInitStage2(): it shows “Loading shaders” on its first frame and calls stage 2 on its second. A patch that
assumed stage 2 (shaders, cursors, hotkeys, the login check) always runs after assets and sounds have loaded can no
longer rely on the loading screen to enforce that. Stage 2’s ShaderRegistry.Load() now also registers the default
shader programs itself (the static constructor that did it is gone; see Shaders).
Other start-up changes in ScreenManager: registerSettingsWatchers() adds watchers on optimizeRamMode and
developerMode that call a new private setupJsonLoadSettings(), which calls
JsonUtil.setupLoadSettings(OptimizeRamMode == 2 && !DeveloperMode) (see the API chapter); loadCursors() loads a
new trim cursor; LoadCursor(string) no longer skips macOS, so custom cursors now load there too; the glintmod
check is null-safe on ModContainer.Info; the command-line world start sets StartServerArgs.DeveloperMode.
Member (1.22.7)
1.23.0-pre.1
What to do
ScreenManager.DoGameInitStage1() (public)
first statements reordered; one more Logger.Notification call
Re-anchor transpilers on the call order
GuiScreenLoadingGame.RenderToDefaultFramebuffer(float); field accum (private)
no wait on loadingText; accum and the “Waiting for async sound loading…” log removed
Do not rely on stage 1 having finished when stage 2 runs
LoadScreen(GuiScreen), LoadScreenNoLoadCall(GuiScreen) and LoadAndCacheScreen(Type) now call
CurrentScreen.OnScreenUnload() on the outgoing screen before the dispose check (which is unchanged). StartMainMenu()
used to assign CurrentScreen = mainScreen and call OnScreenLoaded() directly; it now calls LoadScreen(mainScreen).
StartGame(bool, StartServerArgs, ServerConnectData) used to assign CurrentScreen = new GuiScreenConnectingToServer(...)
directly; it now calls LoadScreen, so the outgoing screen gets OnScreenUnload() and is disposed (unless cached), and
GuiScreenConnectingToServer gets the base GuiScreen.OnScreenLoaded(), which runs the cached-session-key check
(inferred effect: an expired session now redirects to the login screen at this point). Because initMainMenu() still
disposes CurrentScreen (and clears the screen cache) first, the screen that is current when StartMainMenu() runs now
gets one more Dispose() call, from LoadScreen, and an OnScreenUnload() after it has been disposed (read from the
code path, not traced at run time; make Dispose overrides idempotent). GuiScreenCredits now overrides OnScreenLoaded() to rebuild its
layout and no longer runs the base session check.
// ScreenManager.LoadScreen(GuiScreen), 1.22.7
if (CurrentScreen !=null&&!CachedScreens.ContainsKey(CurrentScreen) && screen != CurrentScreen && screen !=null&&screen.ShouldDisposePreviousScreen)
GuiScreenRunningGame.ExitOrRedirect(bool, string, EnumExitMode) now reads runningGame.GetRedirect() before
DestroyGameSession and, on a normal (not disconnect) exit with no local server still running, calls
ScreenManager.TryRedirect and returns instead of calling StartMainMenu(). In 1.22.7 the redirect ran after the
branch in every case, including disconnects and after StartMainMenu(). TryRedirect(MultiplayerServerEntry) (internal)
now calls AskForConnectToMultiplayer, so a server redirect shows a confirmation screen instead of connecting at once.
Reconnect() (private) follows a pending redirect instead of reconnecting to the same server. OnWindowClosed() now
waits up to 30 seconds (600 polls of 50 ms) for Platform.IsServerRunning to clear before returning;
ReloadWorld’s wait loop sleeps 10 ms instead of 5.
Member (1.22.7)
1.23.0-pre.1
What to do
GuiScreenRunningGame.ExitOrRedirect(...) (public)
redirect captured early; early return on redirect
Postfixes that assumed the main menu is loaded afterwards may now see the confirmation screen
MainMenuAPI and MainMenuInputAPI implement the new ICoreClientAPI and IInputAPI members (see the API chapter).
Most of them throw NotImplementedException in the main menu. Note that MainMenuAPI.PlatformUtils throws while the
obsolete Forms still works there, so main-menu code should keep using Forms for now.
ModContainer.Info can now be null (a mod whose modinfo failed to load; see Mods), and the screens
handle it: GuiScreenMods.LoadModCells() lists such a mod by file name with “ModInfo failed to load!”;
GuiCompositeMainMenuLeft, GuiScreenWorldCustomize, SystemModHandler, ModDbUtil and CrashReporter skip it or
print its file name. GuiScreenWorldCustomize’s mod sort keeps core mods first (rewritten, same order) and falls back
to the file name when a mod has no name. The singleplayer screens (GuiScreenSingleplayer, GuiScreenSingleplayerModify,
GuiScreenSingleplayerNewWorld) now set StartServerArgs.DeveloperMode (an internal field) from
ClientSettings.DeveloperMode; GuiScreenSingleplayerModify shows SaveGame.GetSeedWorldgenForGUI() instead of
SaveGame.Seed; GuiScreenSingleplayer probes saves with requireWrite: false; the new-world dice button now has the
key "dice" and plays a pitched diceroll sound.
ClientSystemStartup checks the server’s network version against "1.23.2" (was "1.22.6"); it now calls
Lock() on CollectibleTagRegistry and EntityTagRegistry straight after registering the server’s tags; it loads the
server’s recipes through game.GetCustomRegistry(code) instead of GetRecipeRegistry (see the API chapter); and it
allocates ClientMain.BleedOverlayTextureSubIdsByBlockId as int[][] plus a new BleedCornerOverlayTextureSubIdsByBlockId
(see Textures, atlases, bleeding and decals). ClientLogger’s constructor now sets ILogger.fallback and ILogger.instance (see the API
chapter).
ClientMain (public, sealed) is the client’s GameMain. Its changes are small but touch fields that mods reach
for often.
Sizes.Width and Height now return Platform.FramebufferSize (pixels) where they returned
Platform.WindowSize; the new WindowWidth and WindowHeight return the window size. OrthoMode in
RenderToDefaultFramebuffer(float), the aspect ratio in Set3DProjection(float, float) and the viewport in
OnResize() use the framebuffer size. See the platform section below for what the two sizes mean.
Client systems.Start() builds clientSystems as a ClientSystem[39] (was 40): SystemCinematicCamera is
gone from the engine (it is now Vintagestory.GameContent.SystemCinematicCamera in VSEssentials, see the base game
mods chapter), so every system after SystemRenderSunMoon moved up one index. Find systems by type or Name,
never by index.
Removed and renamed fields.AllowFreemove is gone (fly-mode hotkeys and .freemove no longer test it).
currentGroupid is now CurrentGroupId.
EntityDebugMode is no longer an auto-property: the setter stores a private entityDebugMode, and the getter
returns it only while the player is in creative mode.
New settings watchers in the constructor: retroMode (sets RuntimeEnv.RetroMode and queues
ReloadTextures on the main thread) and liquidDepthFullResolution (rebuilds the framebuffers). See Client
settings.
OnFowChanged(int) no longer sets MainCamera.ZNear; the Camera.Fov setter does (see Camera).
OnOwnPlayerDataReceived() resets ClientSettings.Minbrightness to 0 when it is not 0 and the player lacks the
new Privilege.minbrightness (see the API chapter).
ExitAndSwitchServer(MultiplayerServerEntry) sets doReconnect instead of exitToMainMenu, so a server
redirect goes through the reconnect path (the screen side is under “Leaving a running game and redirects”).
SendPacket(byte[]) calls MainNetClient.SendUncompressed (was Send; see Networking). Connect() no longer
logs the UDP local endpoint.
Dispose() also disposes CollisionScene (see Collision). TrySetWorldConfig(byte[]) reads through the span
overload of TreeAttribute.FromBytes. The debug screen gets a memcomitted line.
Bleeding fields changed type; see Textures.
Member (1.22.7)
1.23.0-pre.1
What to do
ClientMain.Width, Height (public)
framebuffer size; new WindowWidth, WindowHeight
Use Width/Height for GL work, WindowWidth/WindowHeight for anything in window coordinates (mouse)
ClientMain.clientSystems (40 entries)
39 entries, SystemCinematicCamera removed
Look systems up by type or Name
ClientMain.AllowFreemove (public field)
removed
Gate fly mode in your own code
ClientMain.currentGroupid (public field)
CurrentGroupId
Rename reflection and transpiler field references
ClientMain.EntityDebugMode (auto-property)
property over private entityDebugMode; true only in creative
ScreenManager.ConnectToMultiplayer(string host, string password) was public and resolved the host synchronously; it is
now internal and takes a task: ConnectToMultiplayer(Task<ServerConnectData> connectionProvider, string? password), which
reads connectionProvider.Result. Callers build the task with ServerConnectData.FromHostAsync(host). The
vintagestoryjoin:// confirmation moved into a new internal AskForConnectToMultiplayer(string host, string? password),
which now confirms every host (not only join links), starts FromHostAsync before the player answers, and is used by
UriHandler.HandleConnect and TryRedirect. The command line, the saved-server list, the public server view, the
server dashboard and the mod download screen call ConnectToMultiplayer directly, with no confirmation. Errors from
the task arrive wrapped in an AggregateException, so the disconnected screen’s message changes form (inferred).
ServerConnectData split its work into internal async helpers. TryResolveConnectionStringAsync returns an error
message instead of throwing for unknown, expired or empty vintagehosting (vh-) addresses; FromHostAsync turns that
into an ArgumentException. PerformDnsSvrLookupAsync returns a DnsSvrLookupResult instead of logging inline; note
that a missing SRV record now reports DnsSvrLookupOutcome.NoServers, so FromHostAsync logs “No name servers found”
as an error where 1.22.7 logged “No SRV record found” (observed in the code; harmless, the supplied host is still used).
The multiplayer screen now probes every saved server. GuiScreenMultiplayer builds a raw server-query packet once (static
constructor), and OnScreenLoaded() starts one probe task per entry (StartProbingServerAsync, which opens a TCP
connection, sends the query and repeats with an IncrementalBackoff from 30 seconds, growing 1.5 times per failure, up
to 5 minutes) plus a task that animates the probing dots; OnScreenUnload()
cancels them. The cells changed from SavegameCellEntry / GuiElementMainMenuCell to ServerCellEntry /
GuiElementServerCell (see the API chapter), and InitGui() runs only when the composer is not yet composed.
required members with [JsonProperty(Required = Required.Always)] (all but serverUrl and gameDescription); the parameterless constructor carries the compiler’s required-members [Obsolete] error
Set every required member in an object initialiser, or use the new ServerListEntry.MakeFakeEntry(); a master-server entry missing a field now fails the whole list
The platform layer now keeps two sizes apart. The window size (WindowSize, the OpenTK ClientSize) is in
screen coordinates; the framebuffer size (the new FramebufferSize, the OpenTK FramebufferSize) is in pixels.
They are equal on an unscaled display and differ on a scaled display under Wayland and on macOS. Everything that
allocates or binds GL surfaces now uses the framebuffer size: SetupDefaultFrameBuffers(), LoadFrameBuffer(EnumFrameBuffer)
(the default framebuffer and the blur and god-ray viewports), UnloadFrameBuffer(EnumFrameBuffer),
RenderPostprocessingEffects(float[]) (all viewports, and its width/height locals), RenderFinalComposition()
(invFrameSizeIn), BlitPrimaryToDefault(), SaveScreenshot(...), GrabScreenshot(...) and
Vintagestory.ClientNative.Screenshot.GrabScreenshot. The call count is the same in most of these methods, but the
property read is different (get_FramebufferSize instead of get_ClientSize), so a transpiler that matched the old
getter finds nothing.
ClientPlatformAbstract.FramebufferSize is a new abstractSize2i property; a custom platform subclass must
implement it.
IRenderAPI.FrameWidth and FrameHeight (RenderAPIBase) now return the framebuffer size; the new
WindowWidth and WindowHeight return the window size. RenderAPIBase.PushScissor and PopScissor use the
framebuffer height.
The OpenTK FramebufferResize event is wired to a new private onFramebufferResize, which schedules the same
delayed resize as a window resize. Window_Resize() now rebuilds the framebuffers when the framebuffer size
changes (it compared the client size), stores both sizes, then calls the new public UpdateDpiScale() and, if the
scale changed, fires the guiScale settings watcher.
UpdateDpiScale() sets RuntimeEnv.DPIHScale and DPIVScale from the current monitor’s scale, or under Wayland
from framebuffer size ÷ client size. RuntimeEnv.GUIScale is now the guiScale setting times DPIHScale (set by the
ScreenManager settings watcher and the MainMenuAPI constructor). Divide pixel sizes by RuntimeEnv.GUIScale,
not by ClientSettings.GUIScale, or GUI built on a scaled display comes out the wrong size.
SetMousePosition(float, float) (private) multiplies mouse coordinates by DPIHScale/DPIVScale on macOS and
under Wayland, so mouse positions are in framebuffer pixels there. The old macOS fix, adding
ClientSettings.WeirdMacOSMouseYOffset, is gone along with the setting.
LoadMouseCursor(string, int, int, BitmapRef) scales the cursor image, and now its hot spot, by DPIHScale
(not on macOS); it used ClientSettings.GUIScale.
LogAndTestHardwareInfosStage2() now calls a new private DetectOpenGlCapabilities(), which reads the GL version and
the extension list once and sets three private flags. If ClientSettings.AllowSSBOs is on but the driver lacks vertex
shader storage blocks, at least four storage-buffer bindings, or a storage block large enough for
ModelDataPoolMaxVertexSize * 16 bytes, it logs a warning and sets AllowSSBOs = false. A missing required extension
now throws a plain Exception whose message starts with troubleshooting advice (was NotSupportedException). With
the settings migration turning allowSSBOs back on for everyone (see Client settings), most players now run the SSBO
terrain path.
supportsPersistentMapping (private) is renamed supportsBufferStorage, and is now also true on OpenGL 4.4 and
later without the extension. New private supportsSSBOs and maxShaderStorageBlockSize.
AllocateEmptySSBOMesh(...) now throws NotSupportedException when SSBOs are unsupported and
ArgumentOutOfRangeException when the requested position buffer exceeds the driver’s limit. It falls back to
BufferData when buffer storage is unavailable, and it always (re)creates the shared index buffer when
ClientPlatformAbstract.singleIndexBufferId is 0 (previously only when the size grew).
VAO gained OwnsIndexBuffer (default true; false for SSBO meshes) and an IndexBufferId property that returns
the current shared index buffer for meshes that do not own theirs. The three RenderMesh overloads and
RenderMeshInstanced bind vao.IndexBufferId instead of vao.vboIdIndex; VAO.Dispose deletes the index buffer
only when OwnsIndexBuffer. ClientPlatformAbstract.DisposeIndexBuffer() now also resets singleIndexBufferSize.
UpdateSSBOMesh(MeshRef, MeshData) clamps out-of-range UVs to the valid range instead of zeroing them.
GlClearDepthBuffer() is new on ClientPlatformAbstract (abstract), ClientPlatformWindows and RenderAPIBase
(it backs depth-tested GUI; see the API chapter).
UpdateSoundDevices() (public) is new; the sound engine calls it when the audio device changes (see Sound).
The GL debug callback appends the managed stack trace to the exception it throws on a GL error.
GlGenerateTex2DMipmaps() saves the bound texture’s GL_TEXTURE_BASE_LEVEL, sets it to 0, generates mipmaps and
restores it. BuildMipMaps(int) now calls it instead of GL.GenerateMipmap, and then sets the base level to 2 when
RuntimeEnv.RetroMode is on, 0 otherwise. Every texture whose mipmaps are built through BuildMipMaps (the atlases)
is affected.
LoadOrUpdateCairoTexture(ImageSurface, bool, ref LoadedTexture) clamps the uploaded size to
GlGetMaxTextureSize() and logs an error instead of failing on an oversized GUI surface. A texture taller or wider
than the limit is cropped.
Mouse_WheelChanged was rewritten. The fields of the API’s MouseWheelEventArgs that every handler receives changed
meaning (the type itself is in the API chapter):
Field
1.22.7
1.23.0-pre.1
delta
(int) vertical offset × sensitivity, clamped to ±1 on macOS
(int) vertical offset × sensitivity, no macOS clamp
deltaPrecise
same value as delta (truncated)
the unrounded float
value
running sum of deltas (prevWheelValue)
(int) milliseconds since start (EllapsedMs)
valuePrecise
running sum of deltas
milliseconds since start
DeltaX, DeltaY
-
horizontal and vertical offset × sensitivity
DeltaXInt, DeltaYInt
-
whole steps accumulated over a burst; the remainder carries to the next event
IsFresh
-
true when more than 17 ms passed since the previous wheel event
A handler that used value as a scroll position (zoom levels, list scrolling) now gets a timestamp. Use DeltaY or
DeltaYInt and keep your own total. The private prevWheelValue field is gone; new private lastScrollMs,
accumScrollDeltaX, accumScrollDeltaY and the constant freshScrollMs (17).
PickingRayUtil.GetPickingRayByMouseCoordinates(ClientMain) became GetPickingRayByMouseCoordinates(ClientMain game, int mouseX, int mouseY); it unprojects against WindowWidth/WindowHeight (window coordinates) instead of Width/
Height. The new IInputAPI.GetPickingRayFromMousePosition overloads (see Input) call it.
The order-independent transparency targets moved out of SystemRenderOITLayers and into the transparent framebuffer
itself. In 1.22.7 BeforeOIT.rebuild() created a reveal texture and a three-layer accumulation array outside the
framebuffer list and kept their ids in private statics. In 1.23 SetupDefaultFrameBuffers() creates them as part of
FrameBuffers[1] (EnumFrameBuffer.Transparent):
FrameBuffers[1].ColorTextureIds[n]
1.22.7
1.23.0-pre.1
0
Rgba16f 2D (replaced at run time by the OIT reveal texture on attachment 0)
Rgb8 2D, nearest, clamped: the OIT reveal target
1
R16f 2D
unchanged
2
2D (glow)
unchanged
3
-
Rgba16f 2D array, 3 layers, on colour attachments 3, 4 and 5: the OIT accumulation
ColorTextureIds has four entries, so code that iterated it or assumed three breaks. The shader side of the OIT
rewrite is in the shaders chapter.
int liquidResolutionDiv = (ClientSettings.LiquidDepthFullResolution?1:4);
Every local declared after it moves up one slot (the shadow-map width and height locals included), so a transpiler
that loads or stores locals by index in this method breaks.
A renderer that ran after the selection outline at AfterFinalComposition to draw over it, or that expected the
outline drawn after post-processing, now sees it earlier in the frame, before bloom and the final composition. A
Before-stage renderer registered with an order between 0 and 0.03 now runs before the camera updates.
SystemSelectedBlockOutline also draws rotated selection boxes: a box that is a RotatedCuboidf with
IsRotated() true goes through a new private selectionMatrix and the API’s WireframeCube.Render(ICoreClientAPI, Matrixf, float, int) overload (see the API chapter); other boxes keep the old call.
SystemRenderDebugWireframes has a new collider view (wfmodes.Colliders, toggled by .debug wireframe colliders),
drawn by a new private renderColliders(int) from the collision scene within 32 blocks of the player. Its
block-entity view iterates the chunk’s Dictionary<int, BlockEntity> and rebuilds positions with
FastBlockPos.FromIndex3d (see “Block accessors, the world map and chunk data”).
ChunkRenderer.RenderOpaque(float) and SystemRenderEntities.OnRenderOpaque3D(float) read the new
ClientSettings.RetroMode into a new local, doBlend, and pass it to every GlToggleBlend call they make. With
retro mode on, opaque chunks and entities draw without blending, and the entity alpha test rises from 0.05 to 0.4.
Each method gained a local and changed its GlToggleBlend(true) constants into local loads, so transpilers on them
break.
SystemRenderAim.OnRenderFrame2DOverlay(float) sizes the crosshair by RuntimeEnv.DPIHScale (was a fixed 32 px)
and no longer switches to the hostile crosshair by distance when the world config obbCombat is true. A new private
DrawAttackAimIndicator(ItemStack, bool) draws arrows for the held item’s attack direction
(EntityPlayer.GetHeldTpHitAimIndicator, see the API chapter) with four textures generated in the constructor by
GenerateAttackAimArrowTexture(...) and drawn with Render2DTexturePremultipliedAlpha. Dispose frees them.
RenderAPIBase and RenderAPIGame implement the new IRenderAPI members (see the API chapter): MainCamera
(the PlayerCamera, which now implements ICameraAPI), AllowCameraControl, CreateAviWriter,
GetAvailableCodecs, GlClearDepthBuffer, RenderWireframeSphere, WindowWidth and WindowHeight. In
RenderAPIBase the virtual MainCamera, AllowCameraControl and RenderWireframeSphere throw
NotImplementedException, so they work in game but not in the main menu. Note that in 1.23.0-pre.1
RenderAPIGame.AllowCameraControl reads and writes ClientMain.AllowCharacterControl, not
ClientMain.AllowCameraControl. RenderAPIGame.CameraOffset is [Obsolete("Use MainCamera.CameraOffset instead")]. RenderAPIGame.RenderLine now ends in a new private RenderMesh(BlockPos, MeshData), which
RenderWireframeSphere shares.
The near plane formula is the one OnFowChanged used in 1.22.7 (0.1 minus the field of view in degrees ÷ 2250,
clamped to 0.025 to 0.1), but it now runs on every assignment to Fov, including assignments by mods and by the
cinematic camera.
Each chunk tesselation now carries the number of the tesselation request it came from, so a slow, older result can no
longer replace a newer one that was uploaded first. ChunkTesselatorManager.TesselateChunk(...) stamps
centerTesselationId (the chunk’s quantityDrawn, or 0 when the centre was skipped) and edgeTesselationId on the
new TesselatedChunk. TesselatedChunk.AddCenterToPools and AddEdgeToPools dispose the parts and return false
when the id is older than the chunk’s new uploadedCenterTesselationId / uploadedEdgeTesselationId, and record the
id after a successful upload. MergeIfEqual carries the ids over with the parts and now merges the two bounding
spheres instead of keeping the first.
The retesselation listeners (IClientWorldAccessor “run this when the chunk has been redrawn” callbacks) are fired
against the id of the upload that just completed, not against the chunk’s request counter:
publicvoidTriggerChunkRetesselated(Vec3i chunkPos, int completedTesselationId)
{
...
if (listener.AtDrawCount< completedTesselationId) // 1.22.7: < chunk.quantityDrawn
ChunkTesselatorManager.OnBeforeFrame calls the int overload with tesschunk.centerTesselationId in both its
upload paths. A name-only patch on TriggerChunkRetesselated is now ambiguous, and a patch on the
(Vec3i, ClientChunk) overload no longer sees the engine’s calls.
ClientChunk follows the new WorldChunk.BlockEntities (Dictionary<int, BlockEntity>, keyed by in-chunk index; see
“Block accessors, the world map and chunk data”). PreLoadBlockEntitiesFromPacket returns early for an empty packet,
creates the dictionary on demand and stores by Pos.ToIndex3d(); InitBlockEntitiesFromPacket and the block-entity
update path tolerate a null dictionary. The internal BlockEntitiesCount field is gone. TCTCache.blockEntitiesOfChunk
is a Dictionary<int, BlockEntity>, and ChunkTesselatorManager fills it from the chunk’s blockEntities field (it
may be null). BleedingJsonTesselator.Tesselate looks block entities up by pos.ToIndex3d(). Block entity data is
read with BinarySpanReader and TreeAttribute.FromBytes(ref BinarySpanReader) (see the API chapter), so the
MemoryStream/BinaryReader locals and their using blocks are gone from these methods.
JsonTesselator.AddJsonModelDataToMesh(MeshData, int, TCTCache, IMeshPoolSupplier, float[], IJsonTesselatorHooks, int), the method that writes every JSON-shaped block face into the chunk mesh pools, was rewritten as a two-pass
pipeline built on new private structs (PreparedGeometry, FaceGeometry, FaceSurface, FaceLighting,
PreparedUvMapping, PoolRequest, PreparedMeshFace, MeshWriter, DecorFaceData, and enums EnumMaterialType,
EnumUvSource). It now prepares wind flags (PrepareWindFlags), checks face topology (ValidateFaceTopology),
resolves geometry once (ResolveMeshGeometry), and for each face computes geometry (GetFaceGeometry), culls
(IsFaceCulled) and resolves the texture and pool (TryPrepareFaceSurface, MeshWriter.TrySelectPool). Only then
does it write all faces (PrepareFaceLighting, MeshWriter.AppendFace). Both public signatures are unchanged, but
there is nothing left inside for an old transpiler to anchor on: rewrite it against the new private methods, or move
the patch to a prefix or postfix.
One behaviour change is visible to mods. When a face’s texture has no atlas pool yet, 1.22.7 threw a
RetryTesselationException and the chunk was tesselated again later. 1.23 logs a warning (“Skipping mesh for block
… texture ID … has no atlas pool”) and returns without writing any face of that block; the chunk is not retried
for it. A block that adds textures to the block atlas late (after the atlas pages exist) can now be missing from the
chunk until something else retesselates it (inferred from the code path).
The decor helpers became private: CalcAutoUVsForDecor, ApplyDecorUVs, FindDecorMaxPos and SkipDecorFace (all
public in 1.22.7) are gone, replaced by private TryPrepareDecorFace, WriteDecorUVs and AdvanceDecorOffset. The
private fields decorFace, decorVertexOffset, decoru1, decoru2, decorv1, decorv2, decorSeamAdjustX1 to
decorSeamAdjustZ2 and tmpCoords are gone. BleedingJsonTesselator.TryGetCustomTexture(...) renamed its out
parameter from result to cTexResult (it matters to Harmony __result-style or named parameter injection). Whether
the rewrite produces byte-identical meshes was not checked.
Member (1.22.7)
1.23.0-pre.1
What to do
JsonTesselator.AddJsonModelDataToMesh(..., IJsonTesselatorHooks, int) body
two-pass rewrite
Rewrite transpilers; prefer prefixes and postfixes
Held items can now be animated in third person (the bow is the base game’s example). InventoryItemRenderer.GetItemStackRenderInfo
fills the new ItemRenderInfo.AnimationModelRef, AnimationShape and AnimationModelVariant (see the API chapter)
for EnumItemRenderTarget.HandTp and HandTpOff when no collectible replaced the model in OnBeforeRender. The model
comes from three new public methods on ShapeTesselatorManager:
Method
What it does
GetAnimationModelInfo(ItemStack, int variant, out MultiTextureMeshRef, out Shape)
returns the cached animation mesh (may be null) and the shape, without tesselating
GetAnimationModel(ItemStack, int variant, out MultiTextureMeshRef, out Shape)
tesselates and uploads the animation mesh on first use, with joint ids, through the new internal ShapeTesselator.TesselateBlockForAnimation / TesselateItemForAnimation
GetAnimationCodes(ItemStack, int variant)
lists the shape’s animation codes, loading and unloading the shape if needed
Only shapes in the Vintage Story format with animations, and not voxelised, get an animation model. The meshes live in
new private arrays (blockAnimationModelRefsInventory, itemAnimationModelRefsInventory,
altItemAnimationModelRefsInventory) that are disposed with the others. The inventory tint loop moved into a new
private ApplyInventoryTint(Block, MeshData).
ShapeTesselator.TesselateShape(string, AssetLocation, CompositeShape, out MeshData, ...), TesselateBlock and
TesselateItem now forward to private overloads with a withAnimations flag. Two behaviour changes apply to every
caller: overlay shapes of a CompositeShape (Overlays) are loaded on demand and unloaded again after use
(1.22.7 assumed they were loaded), and an element mesh without custom floats now has CustomFloats = null set
explicitly. ShapeTesselatorManager.CreateMesh(string, CompositeShape, TextureSourceBuilder, ITexPositionSource) now
honours the composite shape’s QuantityElements and SelectiveElements. UnloadableShape.Load makes sure
AnimationsByCrc32 and JointsById exist and validates UV bounds when RuntimeEnv.DebugOversizedUVs is set.
TextureAtlasManager (the base of the block, item and entity atlas managers) can now free a texture while the game
runs and reuse its space. A texture inserted with one of the new InsertTextureOrAddReference overloads gets a
reference count in a new textureReferenceCounts dictionary; ReleaseTextureReference(AssetLocation) decrements it
and calls FreeTextureSpace at zero. Fetching the same texture through a plain GetOrInsertTexture makes it
permanent (the count is removed). The base game mods use it for per-entity blended textures in the entity atlas
(VSEssentials’ BehaviorGenetics) and for mechanical power material variants in the block atlas (see the base game
mods chapter).
Consequences for mods that read atlases:
A sub-id is never reused (the counter only grows), but a freed sub-id keeps its stale entry in
TextureAtlasPositionsByTextureSubId, its name leaves the names dictionary, and its rectangle can come back under a
new sub-id. Code that walks TextureAtlasPositionsByTextureSubId must skip positions whose sub-id has no name, or it
will see two entries over the same pixels (inferred from the code path).
The patch funnel moved. In 1.22.7 GetOrInsertTexture(AssetLocation, ...) called GetOrInsertTexture(AssetLocationAndSource, ...),
so one patch saw every insert. In 1.23 both public overloads and both InsertTextureOrAddReference overloads call a
new privateGetOrInsertTextureInternal(AssetLocationAndSource, out int, out TextureAtlasPosition, CreateTextureDelegate, float, bool addReference). Patch that to see every insert.
The first parameter of GetOrInsertTexture(AssetLocationAndSource, ...) was renamed from loc to path.
GetOrInsertTexture(CompositeTexture, ...) now passes the AssetLocationAndSource (with its source) rather than the
bare baked name.
The array growth in AllocateTextureSpace locks a new private TextureAtlasPositionsByTextureSubId_ResizeLock
instead of the array, writes the new position before publishing the new array, and grows to subId + 128 with a
warning for a sub-id far past the end. RegenMipMaps(int) logs a warning instead of throwing for a missing atlas
number. ReloadTextures() and Dispose() release the cached overlay bitmaps (FinishedOverlays()).
Member (1.22.7)
1.23.0-pre.1
What to do
TextureAtlasManager.GetOrInsertTexture(AssetLocationAndSource loc, ...) (public; the funnel)
GetOrInsertTexture(AssetLocationAndSource path, ...), a forwarder
TextureAtlasManager.LoadCompositeBitmap(ClientMain, AssetLocationAndSource, Dictionary<AssetLocation, BitmapRef>)
parses the new composite-name format. The number before ~ in each ++ part is now unpacked with the API’s
BlendedOverlayTexture.UnpackBlendingToTuple, giving a blend mode, an X and Y offset and the index of the layer it
applies to; each overlay can carry its own alpha after å, multiplied with the base alpha. Overlays no longer have
to match the base size: they are blended at their offset into the layer they apply to, in reverse order, by a new
private static ApplyOverlays(...). An overlay that applies to a later layer stops the chain with a warning. The
name format itself is defined by CompositeTexture in the API (see the API chapter). Code that builds or parses
baked texture names by hand must follow it.
Texture bleeding (blocks whose top texture bleeds into neighbours) gained corner overlays and per-position variants.
ClientMain.BleedOverlayTextureSubIdsByBlockId changed from int[] (one sub-id per block) to int[][] (one array of
variant sub-ids per block), and the new BleedCornerOverlayTextureSubIdsByBlockId holds the corner overlays.
BlockTextureAtlasManager fills both through a new private ResolveBleedOverlaySubIds(CompositeTexture, ...), taking
every baked variant of the block’s BleedOverlayTexture and new BleedCornerOverlayTexture (see the API chapter).
TextureBleedHelper.GetBleedDirections(...) gained int[][] cornerOverlayTextureSubIdsByBlockId, posX, posY and
posZ parameters (its overlay array is now int[][]), picks a variant per position with GameMath.MurmurHash3,
drops a diagonal bleed that repeats a cardinal one (SuppressRedundantDiagonals), and sets a corner overlay when both
adjacent edges bleed with the same corner texture. BleedDirections gained CornerOverlayTextureSubIds.
BlendedTextureManager composes the corners on the GPU along with the edges; its cache key includes them.
Block decals (breaking cracks and the like) used one mesh pool drawn with the first block atlas page. They now keep
one pool per block atlas texture, so decals on blocks whose textures sit on a second atlas page are drawn with the
right texture. UpdateDecal copies the block mesh’s texture ids into the decal mesh, splits it with
MeshData.SplitByTextureId(), and adds each part to the pool for that texture; the renderer loops over the pools and
sets BlockTexture2D per pool. A decal whose mesh has a different UV count from the block mesh is now skipped, and
the block’s own UVs are always written into the custom floats (the length check is gone).
Registration moved out of the static constructor. In 1.22.7 the first touch of ShaderRegistry ran a static
constructor that created the default ShaderProgram objects (registerDefaultShaderProgramsPre) and assigned the
ShaderPrograms.* statics. In 1.23 the static fields use initialisers and ShaderRegistry.Load() does the
registration, so ShaderPrograms.Standard and the rest stay null until ScreenManager calls Load() during
start-up stage 2. A static constructor or early patch that read them now gets null.
MINBRIGHT is written into shader prefixes with CultureInfo.InvariantCulture, so systems with a decimal comma
no longer get a broken #define.
ShaderProgramBase.BindTexture2DArray(string samplerName, int textureId, int textureNumber) is new (it also
implements the new IShaderProgram member; see the API chapter), and ShaderProgram’s uniform scan now recognises
sampler2DArray uniforms. ShaderProgramBase.Dispose() now disposes the program’s UBOs and clears the dictionary.
ShaderProgramStandard.ApplyTexture is a new write-only property for the applyTexture uniform (see the shaders
chapter).
loadRegisteredShaderPrograms reads the asset manager into a local; ReloadShaders() is unchanged.
Attribute packets for entities not loaded yet are queued.ClientSystemEntities used to drop
Packet_EntityAttributes and Packet_EntityAttributeUpdate for an entity id it did not know. They now go through a
new private ApplyOrQueueAttributes(long, Action<Entity>): unknown entities get a queue in pendingAttributes,
applied in order by ApplyPendingAttributes when the entity spawns or loads, retried every tick by
RetryPendingAttributes() (called from OnGameTick before the entity loop) and dropped after 60 seconds or on
despawn. Watched-attribute listeners can therefore fire on spawn for updates that arrived before it.
Despawn packets run on the main thread.HandleEntityDespawnPacket wraps its loop in
game.EnqueueMainThreadTask(..., "despawnentities"), so the despawn, renderer removal and OnEntityDespawn happen
later in the frame than the packet. The despawn goes through GameMain.OnEntityDespawn(entity, reason) (which
calls Entity.OnEntityDespawn and unregisters the entity’s colliders), here, in OnEntityDespawn and in
SystemUnloadChunks.
Entity packets call both overloads.HandleEntityPacket calls Entity.OnReceivedServerPacket(int, SerializedData) and then OnReceivedServerPacket(int, byte[]); block-entity packets do the same (see Networking).
Override one of them only (see the API chapter).
Span readers. Entity full updates, debug attributes and block entity data are read with BinarySpanReader
(Entity.FromBytes(ref BinarySpanReader, bool), see the API chapter). UpdateBlockEntityData(BlockEntity, SerializedData, ClientMain, bool) takes SerializedData instead of byte[].
Animation packets wait for their entity: see “Packet handling on the client”.
Particles.ParticlePoolQuads.SpawnParticles(...) no longer skips particles whose GetRgbaColor returns 0
(1.22.7 skipped them and reduced the quantity by 0.5); they are now spawned. The loop became a for with early
breaks, so transpilers on it break.
HudHotbar follows the new hotbar slot numbering in PlayerInventoryManager (see Player inventories): the skill
slot is active slot number -1, the off-hand -2, and backpack slots are 10 to 13 whether or not a skill item is
present (in 1.22.7 the skill slot was 10 and backpack slots shifted by one when it was filled). OnActiveSlotChanged
highlights GetHotbarSlotIndex(newSlot), moveToHotbarSlot wraps through -1 when a skill item is present, and
OnRenderGUI draws the skill item and its highlight at a new skillSlotBounds beside the off-hand slot. The off-hand
grid is now one slot wide and the hotbar grid is placed to its right. OnMouseWheel reads the new
MouseWheelEventArgs.DeltaX/DeltaXInt/DeltaYInt (horizontal scrolling also moves the slot; see the API chapter) and
no longer tracks prevValue. OnGameTick now refreshes the held-item interaction help whenever
EntityPlayer.Controls.HandUse changes, and only clears it when no hand action is running. Held sounds come from
CollectibleObject.GetHeldSounds(stack, null) instead of the HeldSounds field (see the API chapter). OnKeySlot only
stops a hand action that is HeldItemAttack or HeldItemInteract, no longer a BlockInteract.
when CollectibleObject.IsToolModeToggle(...) is true, the key cycles to the next mode instead of opening the dialog, and key repeat is ignored via IInputAPI.PreviousKeyboardKeyState
See the API chapter for IsToolModeToggle; re-anchor patches
The API gained 3D models in GUI dialogs (Hud3DElement, Hud3DPanelScene, Hud3DRaycastElement,
Hud3DFilterOverlaySet; see the API chapter). The engine’s side is small: the new IRenderAPI.GlClearDepthBuffer()
(implemented by RenderAPIBase and the platform) lets a dialog clear depth before it draws its model, and a public
sample, Vintagestory.Client.NoObf.Hud3DTest (a Hud3DRaycastElement), shows the base game’s sailed boat with its
animations. .dev hud3dtest toggles it; clicking the model cycles the animations. Read it as a worked example of the
API.
SystemMouseInWorldInteractions.HandleHandInteraction(float) (private) was restructured into early returns. For a held
item it now stores the result of CollectibleObject.OnHeldUseStep in a local, then checks the new
EntityPlayer.RequestedHandUseCancelReason (see the API chapter): if set, it clears it, calls
TryStopHandAction(false, reason) and, if that succeeds, sends a cancel packet, sets a new
ignoreMouseInteractionsUntilRelease flag and returns. UpdatePicking(float) then ignores the mouse until both buttons
are released. A transpiler that matched OnHeldUseStep followed directly by set_HandUse no longer finds it.
Block selection changed too. UpdateCurrentSelection()’s block filter is now
block == null || (notMeleeAttackFiltered(pos, block) && (renderMeta || notAHiddenMetaBlock(pos, block))): while
EntityPlayer.IsPerformingMeleeAttack is true, blocks with no collision boxes, or with the block attribute
meleeAttackPermeable: true, cannot be selected, so a swing passes through grass and similar blocks. The picking ray
comes from PickingRayUtil.GetPickingRayByMouseCoordinates(game, MouseCurrentX, MouseCurrentY) (the platform-side
signature change is under “Platform and window”). OnBlockPick (middle click) in creative now also checks
selectedHotbarSlot.CanHold(new DummySlot(blockStack)).
uses the manager’s own player and player.Entity instead of game.player/game.EntityPlayer; stops only HeldItemAttack/HeldItemInteract; returns false if there is no ground inventory; ActiveHotbarSlot from the base
despawns the stale entity through game.OnEntityDespawn(oldEntity, reason) (which still calls Entity.OnEntityDespawn and also unregisters its colliders)
Transpilers matching callvirt Entity.OnEntityDespawn here break
ScreenManager.PlaySound(string) and PlaySound(AssetLocation) (public static) each gained a required
bool randomizePitch; when true the sound gets a pitch between 0.8 and 1.2 from a new static rand. There is no
overload without the flag, so calls and patches against the old signatures fail to bind.
In “Aggressive Optimize” RAM mode (ClientSettings.OptimizeRamMode == 2) sounds are now decoded on demand.
ScreenManager.LoadSoundsSlow(ClientMain) became LoadSoundsSlowAsync(ClientMain): for the priority sounds (weather,
environment, temporal storm, rift) it calls the new AudioMetaData.Preload(), which only reads the file, instead of
Load(), which decodes to PCM; the full decode of everything else still only runs in the other modes. The per-asset
verbose logging (ClientSettings.ExtendedDebugInfo) is gone and the pause between priority sounds is 10 ms (was 15).
AudioMetaData now guards DoLoad(), Preload() and Unload() with a private loadLock.
The in-game sound engine now notices device changes: SystemSoundEngine registers a 2-second tick,
OnGameTick2000ms, which compares the OpenAL default device and the available device list with the last ones seen and
raises a private OnSoundDevicesChanged event, wired to ClientPlatformWindows.UpdateSoundDevices() (see
“Platform and window”). AudioOpenAl.CurrentDevice now reads AlcGetString.AllDevicesSpecifier instead of DeviceSpecifier, so it
matches the names in Devices (inferred).
Member (1.22.7)
1.23.0-pre.1
What to do
ScreenManager.PlaySound(string) (public static)
PlaySound(string name, bool randomizePitch)
Pass false for the old behaviour; update patch targets
new subcommand colliders (OnCmdColliders, toggles wfmodes.Colliders)
None
ClientSystemDebugCommands.OnCmdFov (private)
with no argument prints the current FOV; the 60-degree minimum now applies in survival mode instead of in multiplayer; messages go through Lang.Get
Re-anchor
ClientSystemDebugCommands atlas export
Path.Join instead of Path.Combine
None
Cosmetic or near-cosmetic changes, no behaviour change: ClientProgram and ClientProgramArgs (version strings),
GuiElementModCell (version string), GuiScreenServerDashboard (version string, explicit out types; its join call is
in the server-browser table), GuiDialogTransformEditor (nullable annotation), ClientWorldPlayerData
(DesiredViewDistance declaration moved), SessionManager (login version string; the newest-version URL is under
start-up), GuiScreenConnectingToServer (framebuffer size and GUI scale only). One cosmetic change does shift IL: in
ClientSystemDebugCommands, GuiScreenSingleplayer and GuiDialogSelboxEditor the string.Format argument buffers now
use System.Runtime.CompilerServices.InlineArray4<object>/InlineArray6<object>/InlineArray8<object> instead of the
compiler-generated <>y__InlineArrayN<object> types, so a transpiler that names those types breaks.
settingsVersion goes from "1.16" to "1.17". On the first start of 1.23 a one-off migration in
ClientSettings (the SettingsVersion == "1.16" branch) sets liquidDepthFullResolution to true,
maxParallelModDownloads to 3 and allowSSBOs back to DefaultSSBOsSetting(), and, when RuntimeEnv.DPIHScale is
above 1, divides guiScale by the DPI scale (rounded to eighths, at least 0.5) so the effective GUI size stays the
same now that the DPI scale is multiplied in.
Setting (key)
1.22.7
1.23.0-pre.1
Notes
retroMode (ClientSettings.RetroMode)
-
new, false
Mirrored to RuntimeEnv.RetroMode; toggling reloads textures. Texture base level 2, no blending for opaque chunks and entities (see Rendering); the API side steps animations and wave counters (see the API chapter). No settings-dialog row in pre.1: set it in clientsettings.json or with .clientconfig
reset to 0 on joining a world without Privilege.minbrightness
See ClientMain
The settings dialog (GuiCompositeSettings) lost its hover-text arrays: each row now calls Lang.Get with the same
key inline, so a transpiler that indexed hoverTexts breaks, and the order of Lang.Get calls changed. Tab widths
divide by RuntimeEnv.GUIScale; the GUI-scale slider’s maximum (24 instead of 16) depends on the screen width divided
by the DPI scale; the Interface tab has a new switch for focusWindowOnModInstallRequest (the setting existed);
SetCustomPreset uses First() instead of FirstOrDefault(); a language entry without a code is skipped with a
debug log; the sound device list is built without Append. No graphics rows were added or removed.
Mod discovery, side filtering and source-mod compilation all changed, and the engine dropped SharpZipLib.
Discovery.ModLoader.CollectMods() (private) now skips every entry in a mods folder whose name starts with ., and
builds containers through the new factory ModContainer.CreateIfSourceTypeIsUnderstood, which returns null for
anything it does not recognise. ModContainer.GetSourceType(FileSystemInfo) now returns null for a folder that has
no modinfo.json among its direct children. The match is ordinal, so ModInfo.json does not count, even on Windows.
In 1.22.7 such a folder was listed and then errored with “Missing modinfo.json”. Now it is skipped without a message,
so it no longer appears in the mod list at all.
Side filtering moved into LoadMods. After dependency sorting, ModLoader.LoadMods(EnumAppSide side, ...) sets
ModStatus.Disabled on every enabled mod whose Info.Side does not include side, and logs “Mod {0} is disabled
because it is not compatible with the current side”. Such a mod is not unpacked, its assembly is not loaded and its
assets are not added as an origin. In 1.22.7 a wrong-side code mod was loaded and then marked ModStatus.Unused in
ModContainer.InstantiateModSystems. A content-only mod (no assembly) was never side-checked, so its assets loaded on
both sides. Now a "side": "Server" content mod loads nothing on the client, and IsModEnabled returns false for it
there.
Source (.cs) mods are no longer compiled to read their mod info. In 1.22.7, ModContainer.LoadModInfoFromCode
(private) compiled the sources and read [ModInfo] and [ModDependency] from the compiled assembly. Now it parses
each file with Roslyn’s syntax tree only, through the new SourceModInfoReader.TryRead(string), and compilation
happens later, in ModContainer.LoadAssembly, after dependency sorting and only for enabled mods. Consequences:
Only string and bool literals are read from the attribute: Name, ModID (positional), Version, CoreMod,
NetworkVersion, Description, Website, Authors, Contributors, Side, RequiredOnClient and
RequiredOnServer. Constants, nameof and interpolated strings are ignored.
[assembly: ModDependency], WorldConfig and IconPath are not read for source mods. A source mod therefore
declares no dependencies and no world config.
ModContainer.LoadModInfoFromAssembly(Assembly, out ModWorldConfiguration) (private) is no longer called. A patch on
it does nothing.
Compile errors now surface from LoadAssembly (status Errored, ModError.Loading), not from LoadModInfo.
Compilation references.ModCompilationContext(EnumAppSide side) adds System.Linq.dll, System.Collections.dll
and System.IO.Compression.dll on both sides, and on the client OpenTK.Graphics.dll and OpenTK.Core.dll. The
references field changed from string[] to List<string> (reflection). ModLoader now creates the context in its
constructor instead of a field initialiser.
Zip handling. The engine no longer references ICSharpCode.SharpZipLib. ModContainer.Unpack(string),
LoadModInfo(...) (zip branch) and the private loadBackground(string) use System.IO.Compression.ZipArchive:
GetEntry, ZipArchiveEntry.Open() and ExtractToFile(outputPath, overwrite: true). A directory entry is now one
whose FullName ends in /. The path-escape check is ordinal. SourceModInfoReader, FolderOrigin and
PathOrigin do not handle zips; zips are always unpacked to the cache folder first. A mod that used SharpZipLib
through the game’s copy must bundle it (see the bundled libraries chapter).
Null-safety only: ModLoader and ModContainer.CheckProperVersions() now tolerate Info == null in log messages and
in the block-list and dependency checks.
Member (1.22.7)
1.23.0-pre.1
What to do
ModContainer(FileSystemInfo fsInfo, ILogger parentLogger, bool logDebug), public
private parameterless constructor; new public static ModContainer? CreateIfSourceTypeIsUnderstood(FileSystemInfo fsInfo, ILogger parentLogger, bool enableTraceLogging)
Call the factory and handle null. Patch the factory, not .ctor
ModContainer.GetSourceType(FileSystemInfo)
returns null for a folder without a direct modinfo.json child
ModDbUtil moved to 64-bit ModDB tag ids and new query parameters. GameVersionEntry.TagId (public field) is now
long. Search takes long[] gameVersionIds and a long majorVersionId (was string mv) and sends
gameversions[]= and gameversion= (was gv[]= and mv=). The cached selfGameVersionId and sameMinorVersionIds
fields and loadVersionIds are gone; the four search command handlers were renamed and now match version names without
a v prefix (a leading v in the argument is stripped). The private search helper no longer prints usage for a null
search text and limits results to 11. ModDbUtil.DownloadProgressDelegate is replaced by
Vintagestory.Common.DownloadProgressDelegate(long downloadedBytes, long? totalBytes): an unknown total is now null,
not 0. DownloadModAsync hands the transfer to VSWebClient.DownloadAsync and deletes the partial file when
cancelled. onInstallCommand accepts a null game version and uses the running version.
Member (1.22.7)
1.23.0-pre.1
What to do
GameVersionEntry.TagId (int)
long
Recompile; reflection reading it as int fails
ModDbUtil.Search(string, Action<ModSearchResult>, int[], string? mv, string? sortBy, int limit)
Search(string, Action<ModSearchResult>, long[] gameVersionIds, long majorVersionId = 0, string? sortBy, int limit)
GuiScreenDownloadMods (public) now installs on the thread pool. beginInstallation() became
beginInstallation(CancellationToken), which queues the new private installAsync(CancellationToken). Downloads run at
most ClientSettings.MaxParallelModDownloads at a time (a SemaphoreSlim), progress text is throttled per entry through
the new ModInstallState.LastStatusUpdateMs and a debounceStopwatch, the title counts completed mods
(modinstall-downloading), and leaving the screen while installing cancels through cancelCts. failedMods moved
from a field to a local. Joining after the download uses ConnectToMultiplayer(ServerConnectData.FromHostAsync(...)).
GuiScreenGetUpdate (internal) fetches the release list over HTTPS and downloads through
VSWebClient.DownloadAsync with a DownloadProgressDelegate. downloadInstaller, onReleasesDownloadComplete and
onProgress became one downloadInstallerAsync(GameReleaseVersion, CancellationToken); the two cancellation sources
became one downloadCTS, and releases is a local. ServerCtrlBackendInterface also moved to https:// for its
version lists. GuiScreenOnlineMods.Search() passes Array.Empty<long>() and 0L.
SystemModHandler passes EnumAppSide.Client to the new first parameter of ModLoader.LoadMods (see
Mods) in both places it loads mods, and its mod-list queries skip mods whose Info is null.
AssetManager gained a debug flag, single-asset reload and file watching. The interface side (IAssetManager.Reload,
WatchCategory, UnwatchCategory, IAssetOrigin.TryResolveAsset, IAsset.FullFilePath) is in the API chapter.
The constructor takes bool debug and writes it to the new public static bool AssetManager.Debug (default true
until the first constructor runs). The client passes ClientSettings.DeveloperMode. The server passes
ServerMain.InDeveloperMode, which comes from the start arguments; single player copies the client setting into them.
The flag is static, so in single player the client and server share it.
AssetManager.Reload(IAsset) reads the asset again through asset.Origin.TryLoadAsset. It returns false for runtime
assets, and removes the asset (RemoveAsset) if the read fails. It stores the passed instance in Assets, replacing
the old object. It does not re-apply JSON patches. It adds the instance to the per-category list only if
list.Contains(asset) is false, and with the new Asset.Equals an old instance at the same location counts as
contained. So the category list keeps the old object (inferred: lookups by category can return the stale data).
WatchCategory(AssetCategory, AssetChangedDelegate, string filter = "*.json") creates an AssetCategoryWatcher.
Nothing in the engine calls it. In the base game, the server-side state tree system calls it only when VSEssentials’
server config EnableAssetHotReloading is true (default false). It is not tied to developer mode.
AssetCategoryWatcher puts one FileSystemWatcher (subdirectories included, NotifyFilters.LastWrite, Changed
events only) on <origin>/<domain>/<category> for each domain of a FolderOrigin, and on <origin>/<category> for
other origins. It reacts only to a file that the origin can resolve, that is already in Assets, and whose current
winner is that same origin. New files are not picked up: FolderOrigin.TryResolveAsset uses a path table built when
the origin scanned its folder. Each asset is debounced for 100 ms. AssetManager.Reload and then the callback run on
a thread-pool timer thread, not the main thread.
WatchCategory on a category that is already watched replaces the old watcher without disposing it.
UnwatchCategory on a category that is not watched throws KeyNotFoundException. AssetManager never disposes its
watchers at shutdown (inferred: they live until unwatched).
Asset.FilePath changed from a public field to an auto-property, public string FilePath { get; set; }. Mods compiled
against 1.22.7 that read or write Asset.FilePath fail with MissingFieldException (IAsset has no FilePath), and
GetField("FilePath") returns null. Recompiling fixes source access; reflection must use GetProperty.
New FullFilePath { get; set; }. Only PathOrigin fills it, and only while AssetManager.Debug is true.
FolderOrigin, which serves the base game through GameOrigin and every mod, leaves it null.
Asset now implements IEquatable<Asset>. Equals(object) was Location.Equals(obj), which was true only when obj
was an equal AssetLocation. Now it is Equals(obj as Asset): two Asset objects with equal locations are equal,
and an Asset never equals an AssetLocation. This changes List<IAsset>.Contains, Remove and IndexOf and
HashSet<Asset> behaviour.
Asset.ToObject<T>(JsonSerializerSettings) calls Shape.ValidateUvBounds(ServerMain.Logger, Location) on a Shape
result when RuntimeEnv.DebugOversizedUVs is set (default false; the engine never sets it).
FolderOrigin.GetAssets(AssetCategory, bool), FolderOrigin.GetAssets(AssetLocation, bool) and the same two on
PathOrigin now sort their result with AssetLocation.CompareTo, an ordinal compare of domain:path. In 1.22.7 the
order was the file system’s enumeration order. Code that depends on the order of assets within one origin now gets
the sorted order on every platform: registration order of types, and the order one mod’s patches are applied
(inferred).
FolderOrigin gains protected readonly Dictionary<string, AssetLocation> _pathLookup (full path to location,
case-insensitive), filled in the constructor’s scan, and TryResolveAsset(string fullPath, out IAsset asset).
PathOrigin.TryResolveAsset(string filePath, out IAsset asset) resolves any path under OriginPath. Custom
IAssetOrigin implementations must add TryResolveAsset (see the API chapter).
AssetSchemaExporter and the embedded dialogue schema
AssetSchemaExporter (public static) has one public entry point:
bool ExportSchemas(string gamePath, List<string>? additionalModSearchPaths = null, bool force = false). Nothing in
VintagestoryLib, Vintagestory, VintagestoryServer, ModMaker or the three base-game mod assemblies calls it in
1.23.0-pre.1, so it runs only if a tool or mod calls it. When <gamePath>/Schemas/.version is not 1.23.0-pre.1 (or
force is set), it does the following:
Deletes *.schema.json in that folder and calls AssetRegistry.Clear().
Loads every .dll under <gamePath>/Mods and the extra paths, recursively, skipping hidden, system and dot-files,
into the engine’s AssemblyLoadContext.
Invokes every public static parameterless method marked [RegistersAssetTypes].
Writes AssetRegistry.WriteJsonSchemasToDisk, then every embedded resource named AssetSchemas.*.
Stamps .version.
The engine now embeds one such resource, AssetSchemas.DialogueAsset.schema.json: a JSON Schema (draft 2020-12) for
dialogue assets, with components and orphans arrays of talk, condition and trigger nodes, and a startNode.
Only the exporter reads it. Calling the exporter inside a running game clears the asset type registry
(inferred: types registered earlier are lost).
RecipeRegistryBase now derives from the API’s new CustomRegistryBase and is obsolete (see the API chapter). The
engine renamed its storage and helpers to match. The GameMain and ClassRegistry members are public, but a mod
reaches them only by casting api.World to GameMain or through APIBase.ClassRegistryNative. The grid recipe
registry is now created with RegisterCustomRegistry<RecipeRegistryGeneric<GridRecipe>>("gridrecipes").
GameMain creates a CollisionScene in its constructor and exposes it as public ICollisionScene CollisionScene
(the IWorldAccessor.CollisionScene of both sides; see the API chapter). ClientMain and ServerMain dispose it on
exit.
RayTraceForSelection(IWorldIntersectionSupplier, Ray, ref BlockSelection, ref EntitySelection, BlockFilter, EntityFilter), which every other overload calls, now also asks the collision scene. The new private
getSelectedCollider queries colliders on CollisionLayer.Selection along the ray. It keeps only colliders with a
SelectionPosition that pass bfilter, and only if that block’s GetSelectionBoxes is not null. It builds a
BlockSelection for that position. If it is nearer than the voxel hit, it replaces blockSelection before entities
are tested. A postfix on this method can now see a BlockSelection that did not come from AABBIntersectionTest, and
a transpiler finds two new locals (dimension, colliderSelection).
New public void OnEntityDespawn(Entity entity, EntityDespawnData reason) calls entity.OnEntityDespawn(reason) and
then, in a finally, CollisionScene.UnregisterEntityColliders(entity.EntityId). The client’s despawn paths
(ClientSystemEntities, ClientPlayer, SystemUnloadChunks) and ServerMain’s despawn now call it instead of
Entity.OnEntityDespawn directly. A transpiler that looked for callvirt Entity.OnEntityDespawn in those methods
must look here.
New public bool InDeveloperMode => ClientSettings.DeveloperMode implements ICoreAPI.InDeveloperMode on both sides.
The server’s own flag is IServerAPI.InDeveloperMode (ServerAPI, from the start arguments). On a dedicated server,
sapi.InDeveloperMode reads the client settings class, not the --developerMode start argument, so the two can
differ (inferred).
GetOrCreateDataPath(string), both LoadModConfig overloads and both StoreModConfig overloads now build the path
with Path.Join instead of Path.Combine. They throw ArgumentException if the joined path contains .. anywhere.
An absolute path argument used to replace the base folder; now it is appended under GamePaths.ModConfig or
GamePaths.DataPath. A .. anywhere in the joined path throws, including in a file name such as
my..config.json and in the base path itself (inferred: a data path given with .. makes every call throw).
StoreModConfig(JsonObject, string) writes null when jobj.Token is null instead of throwing.
Parameter names changed (foldername to folderName, filename to fileName), which matters only for named
arguments and Harmony argument injection by name.
FastBlockPos (a struct in the API) gained overloads beside the BlockPos ones throughout. A
[HarmonyPatch(typeof(X), "Name")] without argument types is now ambiguous for these names. A patch on the BlockPos
overload does not see calls made through the FastBlockPos one. The base game already calls some of them, for example
in mechanical power.
Type
New overloads (1.23.0-pre.1)
Notes
BlockAccessorBase
virtual int GetBlockId(FastBlockPos), virtual int GetBlockId(FastBlockPos, int layer), Block GetBlock(FastBlockPos), Block GetBlock(FastBlockPos, int layer = 0), virtual Block GetMostSolidBlock(FastBlockPos), virtual IWorldChunk GetChunkAtBlockPos(FastBlockPos), virtual BlockEntity GetBlockEntity(FastBlockPos), T GetBlockEntity<T>(FastBlockPos)
Use pos.InternalY (dimension-aware)
BlockAccessorReadLockfree
the same set (GetBlockId(FastBlockPos, int) not virtual)
BlockAccessorReadLockfree.GetBlockId(BlockPos) now passes pos.InternalY where it passed pos.Y, so it reads the
right dimension for positions in a mini-dimension. GetBlockId(BlockPos, int) still uses pos.Y. The [Obsolete]
attributes on GetBlockId(int, int, int) and GetBlockId(BlockPos) were removed.
BlockAccessorReadLockfree.GetInterface<T>(BlockPos) (public, threw NotImplementedException) was removed.
BlockAccessorBase.SetSolidBlockInternal(int, BlockPos, IWorldChunk, bool, bool, ItemStack) (protected) no longer
always clears the fluid layer when the new block displaces liquids. It keeps a fluid whose block has the attribute
cannotBeDisplaced: true, unless the new block’s material is EnumBlockMaterial.Mantle. A transpiler on the
SetFluid(index3d, 0) call finds it nested two levels deeper, after a GetFluid and an attribute check.
BlockAccessorRevertable (the revert path for block entity data) now calls the span overload of
TreeAttribute.CreateFromBytes (upd.NewBlockEntityData.AsSpan()). A transpiler matching the byte[] overload no
longer matches.
The block entity map is keyed by the in-chunk index (BlockPos.ToIndex3d(): ((y & 31) * 32 + (z & 31)) * 32 + (x & 31)),
not by BlockPos. The public field became a lower-case field that may be null, behind a public property that
creates the dictionary on first read. AddBlockEntity, RemoveBlockEntity(BlockPos) and
GetLocalBlockEntityAtBlockPos index by ToIndex3d(). They allocate only when adding, and return null or false
while the field is null. The interface property IWorldChunk.BlockEntities changed the same way (see the API
chapter).
chunk.BlockEntities[pos] and TryGetValue(pos, ...) with a BlockPos no longer compile. Use
pos.ToIndex3d() or GetLocalBlockEntityAtBlockPos(pos). Code iterating pairs must take the position from
kv.Value.Pos, since kv.Key is now an int.
Reading the property on a chunk with no block entities now allocates and stores an empty dictionary. Read the
blockEntities field when you only want to check.
Mods compiled against 1.22.7 that touch WorldChunk.BlockEntities fail with MissingFieldException, and through
IWorldChunk.BlockEntities with MissingMethodException (the property type changed).
Member (1.22.7)
1.23.0-pre.1
What to do
WorldChunk.BlockEntities, public field Dictionary<BlockPos, BlockEntity>
public property Dictionary<int, BlockEntity> BlockEntities { get; set; }, lazily created
Key by pos.ToIndex3d(); recompile
IWorldChunk.BlockEntities (explicit implementation on WorldChunk)
removed; the public property implements it
-
-
public Dictionary<int, BlockEntity>? blockEntities field
BlockTypeNet, ItemTypeNet, CollectibleNet and EntityTypeNet (all public) carry the new API properties. They
read nested binary data with the API’s new BinarySpanReader (a ref struct) instead of
MemoryStream plus BinaryReader, so the FromBytes(BinaryReader, …) calls became FromBytes(ref BinarySpanReader, …).
Transpilers on these methods lose the MemoryStream/BinaryReader locals and their using blocks. JSON attributes are
now parsed with JToken.Parse(text, JsonUtil.DefaultLoadSettings). On the client that ignores line info when RAM
optimisation is at its highest setting and developer mode is off.
Member (1.22.7)
1.23.0-pre.1
What to do
CollectibleNet.ToPacket(NatFloat)
ToPacket(INatFloat); writes a new Typeid (0 one, 1 var25 random, 2 any)
One and Var25Random return the shared static Packet_NatFloatOne / Packet_Var25Random: do not mutate the result
SourceFilePath is filled by VSEssentials’ type loader from IAsset.FullFilePath when api.InDeveloperMode is set,
so it is empty for assets served by a FolderOrigin. EntityTypeNet added no new packet fields of its own; entity drop
damage types travel inside the drops bytes (see the API chapter).
The skill slot (hotbar index 10) and the off-hand slot (index 11) now have negative aliases, and the active slot number
no longer shifts when the skill slot is full.
InventoryPlayerHotbar’s indexer accepts -1 (mapped to 10, the skill slot) and -2 (mapped to 11, the off-hand),
through a private getHotbarSlotIndex. The valid range is [-2, Count). PlayerInventoryManager.GetHotbarSlotIndex(int)
is the public copy of that mapping.
PlayerInventoryManager.ActiveHotbarSlot: in 1.22.7, a non-empty skill slot made ActiveHotbarSlotNumber == 10 the
skill slot, and pushed backpack slots to 11 and up. Now numbers 10 and up are always backpack slots
(backpack[n - 10]), and the skill slot is selected with ActiveHotbarSlotNumber == -1. Mods that set or read 10
for the skill slot now get backpack slot 0.
On the client, InventoryPlayerHotbar.OnItemSlotModified resets ActiveHotbarSlotNumber from -1 to 0 when the
skill slot empties.
PlayerInventoryManager.IsVisibleHandSlot(string, int) now treats slot 11 (the off-hand) as always visible. In 1.22.7
it was slot 10.
GetHotbarItemstack(int) bounds-checks (returns null outside [-2, Count)) and accepts the negative aliases.
ActiveTool, OffhandTool, ActiveHotbarSlot, OffhandHotbarSlot and MouseItemSlot are now null-safe and go
through GetOwnInventory/GetHotbarInventory.
TryTransferAway pushes onitemgrabbed only when player.Entity is not null. Its debug text now uses
StringBuilder.AppendInterpolatedStringHandler (IL change only).
In 1.22.7 the off-hand hunger penalty was set inside updateSlotStatMods(List<string>, ItemSlot, string), as stat
hungerrate, key offhanditem, only when the off-hand item had no statModifier attribute. Now the new
public virtual void UpdateOffhandHungerPenalty(IPlayer) sets hungerrate under the key offhandpenalty whenever
the off-hand slot is not empty, statModifier or not, and removes it otherwise. It runs after both the off-hand and
the active main-hand slot change. Mods that read or remove hungerrate/offhanditem to cancel the penalty must use
offhandpenalty, or override UpdateOffhandHungerPenalty.
InventoryCraftingGrid overrides the API’s new BeginMultiUpdate() and EndMultiUpdate(). While a multi-update is
open, FindMatchingRecipe() (internal) only records that a check is pending, and the check runs once when the
outermost EndMultiUpdate closes. EndMultiUpdate without a matching begin throws InvalidOperationException. The
client’s drag-distribute (GuiElementItemSlotGridBase.RedistributeStacks) uses it, so a postfix on
FindMatchingRecipe fires once per drag, not once per slot.
CollisionScene (public, sealed, ICollisionScene, IDisposable) is the engine’s implementation of the new collider
scene. The interface, Collider, CollisionLayer, CollisionQueryFilter and the physics that use it are in the API
chapter. Engine-side facts a mod should know:
There is one scene per GameMain, so the client and server each have their own (two in single player). The scene
only lives in memory; nothing in it saves or syncs colliders.
Colliders sit in a uniform grid of 32-block cells keyed by dimension. A collider spanning more than 4096 cells is
stored with no cells and found only by the full-scan path. A query covering more cells than max(64, occupied cells)
scans every collider instead. Bounds and sweep motion must be finite and ordered, or the call throws
ArgumentException.
Access is guarded by a ReaderWriterLockSlim, and query scratch space is [ThreadStatic], so queries from worker
threads are allowed. RegisterTransformedCollider throws if an owner entity already has a collider with the same
ownerColliderCode. Registering after Dispose() throws ObjectDisposedException.
Collider coordinates are dimension-local: GameMain.getSelectedCollider subtracts dimension * 32768 from the ray’s
Y before querying.
The engine calls UnregisterEntityColliders(entityId) from GameMain.OnEntityDespawn (see above). Colliders with no
owner entity are never removed by the engine; their registrant must call UnregisterCollider.
Besides selection and despawn, the engine itself only reads the scene for the client’s debug wireframes; the
registrations come from the API’s and VSEssentials’ physics behaviours.
Networking: transport (TCP and UDP, client and server)
The wire framing is unchanged: every TCP message is a 4-byte big-endian length whose top bit flags a compressed body,
followed by a protobuf Packet_Client or Packet_Server. The plumbing around it was rewritten. The byte-by-byte
queues (QueueByte, Queue<byte>) gave way to the new public Vintagestory.Common.GrowableCyclicByteArray;
NetIncomingMessage is now a struct; the ReadMessage() methods that returned null became
bool TryReadMessage(out NetIncomingMessage); INetworkConnection takes spans instead of an array and a length; and
ServerNetManager was folded into TcpNetServer. The UDP transport classes (UdpNetServer, UdpNetClient and the
dummy ones) are unchanged.
Behaviour changes a mod can feel:
Sends now wait. The client’s TCPNetworkConnection.Send and the server’s TcpNetConnection.Send(byte[], bool)
and SendPreparedBytes used to start Socket.SendAsync and return. They now call .AsTask().Wait() when the send
does not complete at once, so the calling thread stalls while the socket’s send buffer is full (inferred).
A connection becomes a client later.TcpNetServer and DummyTcpNetServer still queue a
NetworkMessageType.Connect message, but ServerMain.ProcessNetMessage now ignores it. The ConnectedClient is
made on the first Data message, and only if its packet id is 33 (LoginTokenQuery). Id 15 (ServerQuery) is
answered from a cached, pre-framed Packet_ServerQueryAnswer and the socket is shut down without ever making a
ConnectedClient; any other first packet is dropped (its bytes are still counted). Only id 33 wakes a server in
standby (Launch), so server-browser probes no longer start a sleeping server. ServerMain.lastClientId is gone.
ProcessNetMessage runs on the client-packet parsing thread, or on the main thread when ReducedServerThreads is
set.
Stricter first packet.TcpNetConnection.ReceiveData used to accept a first packet whose first protobuf key byte
was 8 or 18. It now decodes the id with the new internal Vintagestory.Server.Network.ClientPacket.PeekIdFast and
accepts only ids 1, 2, 15 and 33; anything else is disconnected as an invalid packet (and the address is added to
TcpNetConnection.blockedIps when TemporaryIpBlockList is on). The game’s own client, single player included,
opens with an empty Packet_Client { Id = 33 }; a custom client or bot must do the same.
A defect in the raw-bytes send.TcpNetConnection.Send(byte[] data, bool isCompressed) rents its framing
buffer from ArrayPool<byte>.Shared but returns the caller’s data array to the pool in its finally, not the
rented one. The shared pool throws ArgumentException for an array whose length is not one of its bucket sizes
(16, 32, 64 … bytes); the method’s outer catch turns that into InvokeDisconnected() and
EnumSendResult.Disconnected, after the bytes were sent. When the length happens to match a bucket, the caller’s
array goes into the pool while still in use (inferred from the code and the .NET shared pool; not run). Only the
raw byte[] paths to a remote client reach this method: IServerNetworkAPI.SendArbitraryPacket(byte[], ...),
BroadcastArbitraryPacket(byte[], ...) and BroadcastPacketInRange(FastBlockPos, byte[]). Network channels, every
Packet_Server send and single-player connections take other paths. A mod that sends raw byte arrays should move
to a network channel or the Packet_Server overloads.
Buffers. The client’s receive queue is a GrowableCyclicByteArray allocated at 5 MiB up front
(TcpNetClient.initialIncomingBufferSize), and TcpNetClient.CurrentlyReceivingBytes now counts only the bytes
waiting in it. NetClient.Send became SendUncompressed; the client never compressed, so only the name changed.
TcpNetConnection.MaxPacketClientId is now static readonly, set from ClientPacket.MaxId (35). Setting it by
reflection after the type is initialised throws on current .NET (inferred).
removed; ReadHeaderUnsafe(ReadOnlySpan<byte>, out int length, out bool isCompressed), WriteHeaderUnsafe(Span<byte>, int, bool), WriteMessageUnsafe(Span<byte>, ReadOnlySpan<byte>, bool)
The new helpers handle the compressed bit as well as the length
NetClient.ReadMessage(), NetServer.ReadMessage() (abstract) and the overrides in TcpNetClient, DummyTcpNetClient, TcpNetServer, DummyTcpNetServer
bool TryReadMessage(out NetIncomingMessage)
Re-target patches; loop with while (x.TryReadMessage(out var msg))
forwards to a new internal CompressOffset4(byte[], int, bool reuseBuffer) with true; that one calls CompressionZSTD.Compress(byte[], int, int, bool) directly when the compressor is ZSTD
A patch on CompressionZSTD.Compress(byte[], int, int) no longer sees calls made through CompressOffset4. The server-assets build uses reuseBuffer: false (a fresh array, not the shared buffer)
forwards to the new internal Compress(byte[], int, int, bool reuseBuffer) with true
Same result
Compression.DecompressCombined(...) (internal)
decompresses with DecompressAndSize into the compressor’s reusable buffer instead of a fresh copy; the palette array is allocated uninitialised and its tail cleared
All changes to the generated protobuf classes add new field numbers, except three renames that keep their numbers and
wire types. Packet_Client.LoginTokenQuery, Packet_ClientIdEnum.LoginTokenQuery (33) and
Packet_ServerIdEnum.TokenAnswer (77) only moved inside their classes, and Packet_ClientSerializer.Serialize now
writes LoginTokenQuery after the other fields instead of first. Protobuf readers do not care about order, so this is
wire-compatible. The id constants are const, so a compiled mod keeps the values it was built with.
0 means INatFloat.One, 1 Var25Random, 2 a NatFloat from Avg, Var and Dist. A packet built without Typeid decodes as the constant 1 and its other fields are ignored. CollectibleNet.ToPacket and FromPacket now use INatFloat
Packet_ItemType.DamageType (50), HeldTpHitCombo, HeldTpHitComboHigh, HeldTpHitComboMid, HeldTpHitComboLow (51 to 54, repeated string, each with Count, Length, Get…, Set…, …Add), HeldTpHitSprintAnimation (55), KnockbackStrength (56), SourceFilePath (57)
Carried by ItemTypeNet
Packet_Client.LoginTokenQuery declared and serialised first
declared and serialised in field-number order
None
Query answer field reuse. Fields 2 and 5 keep their numbers and their wire type (a length-delimited string), so a
reader built against the 1.22.7 schema decodes the description as MOTD, the play style code as GameMode, and
skips 8 and 9. In practice no 1.22.7 game is affected: the 1.22.7 client never sent a ServerQuery, and a 1.22.7
server never answered one (its HandleQueryClientPacket disconnected the connection with “Query complete”). The
renames break only code compiled against the old member names. In the other direction, a 1.23 client probing a 1.22.7
server gets a disconnect instead of a QueryAnswer, and its probe fails (inferred; the client side is under
“Connecting to a server and the server browser”).
IL. Every changed Deserialize gained case labels, and Packet_ItemTypeSerializer.Serialize gained four loops,
which shifts its local indices. Packet_ClientSerializer.Serialize renumbered its locals when LoginTokenQuery moved.
Re-check any transpiler on a generated serializer.
Block-entity messages call both overloads.GeneralPacketHandler.HandleBlockEntityMessage now finds the block
entity through GetBlockEntity(FastBlockPos) and calls the new OnReceivedServerPacket(int, SerializedData) and
then the old OnReceivedServerPacket(int, byte[]). A block entity that overrides both handles each packet twice.
ClientSystemEntities does the same for entity packets. See the API chapter for which overload to override.
Own-player spawn moved. In GeneralPacketHandler.HandlePlayerData, the block that sets game.player, calls
OnOwnPlayerDataReceived(), sets Spawned and sends packet 26 now runs after the privileges and RoleCode are
copied from the packet, not before. Code reached from OnOwnPlayerDataReceived now sees the player’s privileges and
role on first join.
Span readers.HandleSpawnParticles and HandleAmbient read through the API’s BinarySpanReader
(IParticlePropertiesProvider.FromBytes(ref BinarySpanReader, IWorldAccessor),
AmbientModifier.FromBytes(ref BinarySpanReader)) instead of a BinaryReader over a MemoryStream; see the API
chapter.
Animations wait for their entity.SystemNetworkProcess.HandleAnimationPacket now applies a packet through the
new private TryApplyAnimationPacket. If the entity or its loaded shape is missing, the packet is stored in
pendingAnimations (one per entity, the newest wins) and retried by a new 20 ms tick listener,
RetryPendingAnimations, for up to 60 seconds; despawning the entity drops it. Entity.OnReceivedServerAnimations
can therefore run on a later tick, from the retry listener, rather than inside the packet handler.
HandleBulkAnimationPacket now calls HandleAnimationPacket per entry, so a patch on the latter sees bulk entries
too.
Standing pose rides on the position packet. The client NetworkAPI.SendPlayerPositionPacket() asks
PhysicsBehaviorBase.GetStandingColliderPose() and, if there is one, protobuf-serialises it into
Packet_UdpPacket.ChannelPacket (through a new reused standingStream), over UDP or the TCP fallback alike. The
server applies it in ServerUdpNetwork.HandlePlayerPosition (below; the physics side is in the API chapter).
1.22.7 deserialised a zero bitmask word, which protobuf-net omits, as 2, 3, 4 or 5, so the client saw tags the entity did not have (inferred); 1.23 reads 0
ServerMain.HandleEntityPacket builds an Entity.CachedAccessPerms, calls the new
OnReceivedClientPacket(IServerPlayer, int, SerializedData, ref CachedAccessPerms) and then the old byte[]
overload; ServerSystemBlockSimulation does the same for block entities. Override one of them only (API chapter).
The client-packet handler tables, HandleClientPacket_mainthread and ParseClientPacket_offthread are unchanged.
ServerUdpNetwork.HandlePlayerPosition takes a third parameter, Packet_CustomPacket standingPacket = null, which
the UDP dispatch fills from Packet_UdpPacket.ChannelPacket. After a position is accepted, a pose of 1 to 256 bytes
is deserialised as StandingColliderPose and passed to PhysicsBehaviorBase.TryApplyStandingColliderPose(pose, 128.0); a malformed pose logs “Invalid standing collider pose” and is ignored.
The same method now calls entity.Pos.SetFromPacket(packet, entity, !player.HasPrivilege(Privilege.freemove)), so
a player with freemove skips the 128-block jump check (EntityPosExtensions.MaxMovePerPacket, now public).
ServerUdpNetwork.HandleMountPosition accepts a mount position when entity.IsControlledByClient(player.Entity),
instead of IMountable.IsMountedBy (API chapter).
The server NetworkAPI gained a range broadcast and moved its block-entity broadcast to FastBlockPos and
SerializedData. The old BlockPos/byte[] forms were removed from the class; IServerNetworkAPI keeps them as
default interface methods marked [Obsolete(..., true)] that forward to the new ones. A compiled mod that calls
through the interface still runs; a mod that patches or calls the class member directly fails (see the API chapter).
The channel and API broadcast methods keep their params IServerPlayer[] signatures but hand the array to
ServerMain’s new span overloads, so a null element in exceptPlayers now throws NullReferenceException
(1.22.7 skipped it with plr?.ClientId). A null array is still fine.
Sends to every admitted client within (MaxChunkRadius + 1) × 32 blocks horizontally. The byte[] form goes through the TcpNetConnection.Send defect above
Every ServerMain broadcast now takes params ReadOnlySpan<IServerPlayer> instead of params IServerPlayer[], and
picks recipients with client.State.IsAdmitted() && client.Player != null instead of
State != Offline && State != Queued: clients still in EnumClientState.Connecting no longer receive broadcasts.
The skip test is the new private static ContainsPlayer(ReadOnlySpan<IServerPlayer>, int), which reads ClientId
from each element without a null check. The send paths now carry the ConnectedClient instead of the client id:
SendPacket(IServerPlayer, ...) and SendArbitraryPacket cast the player to ServerPlayer and use its internal
client field, so an IServerPlayer that is not a ServerPlayer now throws InvalidCastException (1.22.7 looked it
up by ClientId). Harmony patches that name a span parameter must declare it as ReadOnlySpan<IServerPlayer>, and it
cannot be read through __args (inferred).
BroadcastBlockEntityPacket(int, int, int, int, SerializedData = default, params ReadOnlySpan<IServerPlayer>); copies RawData into a new array and leaves Data unset when empty
Server assets packet.BoxedPacket_ServerAssets (a BoxedPacket holding the Packet_Server) is gone. The assets
packet (id 19) is now serialised once, compressed once with CompressOffset4(..., reuseBuffer: false) and kept only as
those bytes. SendServerAssets(IServerPlayer) waits for it, then sends a clone of the compressed bytes with
SendPreparedPacket when CompressPackets is on and the socket is not a DummyNetConnection, and otherwise
decompresses it and sends a BoxedPacket. The single-player direct hand-off
(DummyNetConnection.SendServerAssetsPacketDirectly) still gets the Packet_Server object, but only inside
BuildServerAssetsPacket. A mod that edited the assets Packet_Server after it was built, or per player before
sending, must now do it inside BuildServerAssetsPacket before serialisation.
Master server: heartbeat, registration and server query
ServerSystemHeartbeat was rewritten as one async loop, enterHeartbeatLoop(), started by tryStartBeating() from
StandbyLaunch, OnBeginRunGame, UPnP completion and config changes. It runs while currentStatePermitsBeating() is
true: not shutting down, AdvertiseServer on, a dedicated server, VerifyPlayerAuth on, UPnP either off or
successful, and a play style known. The 1.22.7 UPnP path registered without checking IsDedicatedServer; 1.23 always
requires it (inferred: a non-dedicated server no longer advertises).
Signing. Each loop start makes a new P-256 key (ECDsaCng on Windows, ECDsaOpenSsl elsewhere), publishes its
SubjectPublicKeyInfo in ServerMain.CurrentServerQueryAnswer.PublicKey, and signs every register request body
(SHA-256, IEEE P1363) into an X-Signature hex header. Heartbeat and unregister requests are not signed.
Token. The master server’s token is kept in ServerConfig.ServerToken, saved, and sent back in the next
RegisterRequestPacket.token. A new /serverconfig servertoken subcommand (registered in OnBeginConfiguration)
shows it and, outside hosted mode, writes it to a temporary file.
Timing. Heartbeats start at every 2 minutes (DEFAULT_INTERVAL). Failures stretch the interval by 1.5 up to
10 minutes (MAX_INTERVAL), successes shrink it by two thirds, through the new internal IncrementalBackoff.
“invalid” re-registers at once, “blacklisted” stops the loop, and “failed” (any non-success HTTP status) drops back
to registering.
Unregister is sent when the loop exits after a successful registration. OnBeginShutdown calls
CancelRemainingBeat(recreateSignal: false) to cut the wait short. In 1.22.7 SendUnregister cleared the token
before sending it.
URLs.SendRequestAsync<T> builds the address with new Uri(new Uri(MasterserverUrl), apiPath) instead of
string concatenation. The default URL ends in /servers/, so nothing changes; a custom URL without the trailing
slash loses its last segment (inferred from Uri rules). Requests are HTTP/1.1 and a bad parse or failure returns a
ResponsePacket with status “failed”, “error” or “timeout” instead of throwing or staying silent.
Server query answer.ServerMain keeps the answer in CurrentServerQueryAnswer (internal readonly
Packet_ServerQueryAnswer) and its framed bytes in currentServerQueryAnswerSerialized, rebuilt by the internal
UpdateServerQueryAnswer(). The constructor sets ServerVersion and NetworkVersion; config load sets Name,
MaxPlayers, Password and ServerDescription; save-game load sets PlayStyle; HandleClientLoaded and
DisconnectPlayer change PlayerCount; the heartbeat sets PublicKey. A mod that changes the server’s name or
description by writing ServerConfig directly must also update CurrentServerQueryAnswer and call
UpdateServerQueryAnswer() (both need reflection), or the browser keeps showing the old values (inferred).
Member (1.22.7)
1.23.0-pre.1
What to do
ServerSystemHeartbeat.TryRegister() (public)
removed; private tryStartBeating()
No public trigger. Changing ServerConfig.AdvertiseServer raises onAdvertiseChanged, which starts or cancels the loop
required members and [JsonObject(ItemRequired = Required.Always)]
A master-server reply missing a field now throws on deserialisation. The constructors carry the compiler’s “required members” obsolete-error marker, so build with C# 11 or later and set every member
InventoryNetworkUtil (public) moved its raw-data entry points to SerializedData and the server player type; see the
API chapter for IInventoryNetworkUtil. The engine’s own ServerSystemInventory calls the
HandleClientPacket(IPlayer, int, Packet_Client) overload, which is unchanged.
checks dirty inventories straight from the packet fields; the invIds, slotIds and lastChanged arrays are built only after the tab switch; calls Send2Slots on failure
The network version is not in NetConstants; it is GameVersion.NetworkVersion, a const the compiler inlines. It
went from "1.22.6" to "1.23.2" (in the API it is now OverallMajorMinor + ".2"), while the game version is
"1.23.0-pre.1". It is baked into ClientPackets (the identification packet), ServerMain.HandlePlayerIdentification
(exact string comparison), ClientSystemStartup (the client’s check of the server), the server’s
Packet_ServerIdentification and the query answer. AuthServerComm sends serverversion = "1.23.0-pre.1" to the auth server.
The framing and the login token exchange are unchanged, so a 1.22.x client and a 1.23 server (or the reverse) get as
far as the identification packet and then disconnect with the disconnect-wrongversion message: mixed-version play is
not possible. Mods are unaffected by this check; their own NetworkVersion travels in the identification packet’s
mod list as before. A mod
that compares against GameVersion.NetworkVersion carries the value it was compiled with and must be rebuilt.
Cosmetic or near-cosmetic.ClientPackets and AuthServerComm changed only version strings.
ServerSystemNotifyPing, the server NetworkAPI’s channel-list send and ServerPackets changed only call targets
(SendPacket(client, ...) instead of the id) or typed their out variables; the first two no longer reach
SendPacket(int, Packet_Server). DummyTcpNetClient and DummyTcpNetServer replaced Monitor.Enter/Exit with
lock (different IL, same behaviour). ConnectedClient gained recentChunkRequestsCount (used by chunk sending), and
its ToString() now references the runtime’s System.Runtime.CompilerServices.InlineArray4<T> instead of a
compiler-generated inline-array type, which changes the IL a transpiler sees. Packet_ClientIdEnum and
Packet_ServerIdEnum only reordered one constant each. GrowableCyclicByteArray and DownloadProgressDelegate are
new; Vintagestory.Server.Network.ClientPacket is new and internal.
The main loop (ServerMain.Process) and the start-up phase order are unchanged. What moved is around them: how a
connection becomes a ConnectedClient, how join and mode-change requests are checked, how entities are spawned and
despawned, and how the server shuts down.
Developer mode.StartServerArgs has a new internal JSON field DeveloperMode; ServerMain.InDeveloperMode
and ServerAPI.InDeveloperMode (the new IServerAPI.InDeveloperMode, see the API chapter) read it, and
ServerMain.Launch passes it to the AssetManager constructor as a third argument.
Connections and the server query.ServerMain.ProcessNetMessage no longer creates a ConnectedClient on
NetworkMessageType.Connect (that case now does nothing). A client is created on the first Data message, and only
if its packet id is LoginTokenQuery (33). A ServerQuery (15) is answered on the network thread from a cached,
pre-serialised Packet_ServerQueryAnswer and the socket is shut down; any other first packet is dropped. The cache is
ServerMain.CurrentServerQueryAnswer (internal), rebuilt by the internal UpdateServerQueryAnswer() on join, leave,
config load, save-game load (play style) and the /serverconfig setters for name, description, max clients and
password. A mod that changes ServerConfig.ServerName and the like directly will not see the answer change
(inferred). The field lastClientId is gone. Socket reading uses NetServer.TryReadMessage(out msg) (see
Networking).
Join checks (HandlePlayerIdentification, private). Network version is "1.23.2". Whitelist and ban lookups
are by player UID only (WhitelistedPlayersByUID, BannedPlayersByUID); an entry that matched by name alone no
longer matches. The “Invalid join data” branch (null name or UID) now returns; in 1.22.7 it fell through to the
ban check. FinalizePlayerIdentification clamps the client’s view distance to Config.MaxChunkRadius * 32.
Mode change requests (HandleRequestModeChange, private). A request that targets another player is refused
outright without Privilege.commandplayer (1.22.7 still applied the view distance in that case and only gated
fly, game mode and picking range). The view distance is now clamped to MaxChunkRadius * 32 and logged to the
audit log; DesiredViewDistance is no longer written here (see Players below). The broadcast Packet_PlayerMode
now carries RenderMetaBlocks.
Chat.HandleChatMessage(IServerPlayer, int groupId, string) (parameter renamed from groupid) refuses a
message to a group the sender is not a member of (“You are not part of the group …”). Group ids below
GlobalConstants.ServerInfoChatGroup are mapped to GlobalConstants.GeneralChatGroup in HandleChatLine.
Entity packets.HandleEntityPacket builds an Entity.CachedAccessPerms, calls the new
Entity.OnReceivedClientPacket(IServerPlayer, int, SerializedData, ref CachedAccessPerms) first and then the old
byte[] overload (API chapter).
Join. After sending server assets, HandleRequestJoin calls
PlayerAnimationManager.OnActiveSlotChanged(ActiveHotbarSlot) on the joining player’s entity.
Spawning and loading entities.SpawnEntity(Entity, EntityProperties) now spawns with the type you pass; in
1.22.7 it ignored it and looked the type up from entity.Code. LoadEntity and SpawnEntity_internal read the
onFirstSpawn argument of AfterInitialized from a new entity attribute "onFirstSpawn" (default false when
loading, true when spawning) and then remove the attribute, so a mod can set it before spawning or loading.
Despawning.DespawnEntity calls GameMain.OnEntityDespawn(entity, data), which calls
entity.OnEntityDespawn(data) and then unregisters the entity’s colliders from the new collision scene. A patch on
Entity.OnEntityDespawn still runs; a transpiler on DespawnEntity sees a different call.
Shutdown.Stop(...) now closes the save database (chunkThread.gameDatabase.CloseConnection()) right after
the last tick, before sockets close. Anything that touches GameDatabase after that, for example in a mod’s
Dispose, gets an InvalidOperationException (inferred from GameDatabase.openedConnection). Dispose() also
disposes CollisionScene.
Console and signals. Console commands run with Caller.FromConsole() (same role, privileges and group as
before). ServerConsole handles /stop on the console thread: during start-up it sets
exitState.Mode = SoftExit, in standby it calls Environment.Exit(0). ServerProgram.OnExit (SIGTERM, SIGINT,
SIGQUIT) no longer enqueues server.Stop("External close event ...") on the main thread; it sets
server.exitState.Mode and the standalone loop then calls Stop("Stop through standalone server exit request", mode). A standalone server still in standby now exits instead of ignoring the signal. A patch that matched the
old stop reason string will not fire.
Logging.ServerLogger’s constructor sets ILogger.instance.Value and, if unset, ILogger.fallback (API
chapter).
New public members a mod may want: ServerMain.SeedWorldgen, GetTotalUnpausedTimeMs(),
GetTotalUptimeMs(), TriggerDidPlaceBlock(IPlayer, int, BlockSelection, ItemStack) and
TriggerDidBreakBlock(IPlayer, int, BlockSelection); the last two run the full core and mod event chain, which
includes the anti-abuse counter (see below). They implement new IServerWorldAccessor members (API chapter).
Every server.SendPacket(client.Id, ...) in the server systems became server.SendPacket(client, ...) or
SendPacket(IServerPlayer, ...), and every BroadcastPacket(packet) became
BroadcastPacket(packet, default(ReadOnlySpan<IServerPlayer>)). The new signatures are listed under “Server broadcast
and send methods”; the call-site change alters the IL of ServerSystemCalendar, ServerSystemWorldAmbient,
ServerSystemUnloadChunks, ServerSystemSendChunks, ServerSystemInventory, ServerSystemEntitySimulation,
ServerSystemBlockSimulation, PhysicsManager and ServerWorldMap.
ServerConfig gained fields and a new anti-abuse level, and its config version moved from "1.10" to "1.12" with
two migration steps. ServerConfig is still read and written with Newtonsoft (MemberSerialization.OptIn).
Anti-abuse.AntiAbuse now defaults to EnumProtectionLevel.Auto (was Off) and a config older than "1.11"
that has Off is migrated to Auto. The level the server acts on is the new, unsaved
ServerConfig.RuntimeAntiAbuse, set by ServerSystemLoadConfig.SetRuntimeAntiAbuseLevel(ServerMain) at config load
and whenever Password, WhitelistMode or AntiAbuse is set (their setters now raise the new events
onPasswordChanged, onWhitelistmodeChanged, onAntiAbuseChanged) and when /allowlan toggles. With Auto:
Server
RuntimeAntiAbuse
Singleplayer, LAN closed
Off
Singleplayer, LAN open
LogOnly
Dedicated, whitelist On or Default, or password set
LogOnly
Dedicated, whitelist Off and no password
Basic (moderates: reverts, rejects and bans)
Any other AntiAbuse value is copied through. LogOnly (3) and Auto (4) are numerically above Basic (1), so a
mod that tests Config.AntiAbuse >= EnumProtectionLevel.Basic, as the engine did in 1.22.7, now reads Auto as
“on”. Use RuntimeAntiAbuse.ShouldLog() / ShouldModerate() (API chapter).
Config migration in ServerConfig load: below "1.11", AntiAbuseOff becomes Auto and
Privilege.minbrightness is granted to the sumod and crmod roles; below "1.12", an http:// master server
URL becomes https://. New default roles include minbrightness.
Renamed and added settings.AntiAbuseTriggerOnBlockBreakCount is removed with no migration, so a saved value
is dropped and AntiAbuseTriggerOnBlockBreakPlaceCount starts at its default of 40. New:
AntiAbuseTriggerOnBlockBreakPlaceCountSlow (2500) and AntiAbuseTriggerOnDurationSlowMin (5). Also new:
FQDN and ServerToken (used by the heartbeat, see “Master server”). Several string properties are now
nullable-annotated (ServerUrl, ServerDescription, Ip, LastLaunchMods, LastLaunchPlaystyle).
Read-only servers.ServerProgramArgs.Readonly (--readonly) opens the save with
requireWriteAccess: false, skips repair mode and the database upgrade, and makes GameDatabase drop every write
(see “Save games, the database and the worldgen seed”). It cannot create a new save.
Map sizes.WorldConfig.ClampToValidMapSize(int, int) and IsValidMapSize(int, int) (public static) are new:
sizes are clamped to 32..max and rounded up to a multiple of 32. The world config’s worldHeight is clamped on
load.
The save now holds two seeds. SaveGame.SeedWorldgen (protobuf member 41, public field) drives terrain; Seed is a
random value unrelated to terrain. SaveGame.CreateNew takes SeedWorldgen from the configured seed or a random one
and always randomises Seed. A world from 1.22 or earlier is migrated once in
ServerSystemLoadAndSaveGame.LoadSaveGame (internal type, private method): when SeedWorldgen == 0 and the world
config has no swappedSeed attribute, SeedWorldgen takes the old Seed, Seed is re-randomised, swappedSeed is
set to true and the save game is stored at once. ServerMain.SeedWorldgen, WorldAPI.SeedWorldgen (throws
before the world is loaded, like Seed) and WorldgenWorldAccessor.SeedWorldgen implement the new
IServerWorldAccessor.SeedWorldgen and IWorldManagerAPI.SeedWorldgen (API chapter). ISaveGame has no
SeedWorldgen, so ISaveGame.Seed is the random seed. The client still receives only Seed
(CreatePacketIdentification), so client code cannot derive terrain from the seed any more.
Engine code that now reads SeedWorldgen: ServerSystemSupplyChunks.InitWorldgenAndSpawnChunks (the
Random used to search for the default spawn), ServerSystemEntitySpawner (the LCGRandom passed to every
RuntimeSpawnConditions.Initialise), and the worldgen error log in ServerSystemSupplyChunks, which prints both
seeds. Still on Seed: ServerSystemCalendar builds GameCalendar with SaveGameData.Seed, whose sunset and
super-moon noise is seeded from it, so a migrated world gets different sunset and super-moon variation (inferred).
BlockAccessorWorldGen does not read either seed; its WorldgenWorldAccessor is now built from server instead of
the cast worldAccessor field (same object, inferred). The base game’s worldgen is the other side of this change:
see the base game mods chapter. Worldgen code that reads World.Seed or WorldManager.Seed must read
SeedWorldgen.
Edge case (inferred, not run): a new world whose configured seed is "0" gets SeedWorldgen == 0 and no
swappedSeed flag, so the next load treats it as a 1.22 world and replaces its terrain seed with the random Seed.
SaveGame.GetSeedWorldgenForGUI() returns Seed for an unmigrated world and SeedWorldgen otherwise;
WorldConfig.loadFromSavegame and the single-player world editor use it. /info seed now prints SeedWorldgen;
the new /info seedsh prints Seed.
SaveGame.EnsureValidMapSize() (public, returns true if it changed anything) replaces the Math.Min clamps in
CreateNew and SetNewWorldConfig. It also runs on every load of an existing save: a world whose size is not a
multiple of 32, or out of range, is resized, a warning is logged and the save game is stored.
LoadSaveGame now stores the save game immediately when it moved player data out of the save, applied
SetDefaultSpawnOnce, fixed the map size or migrated the seed. After either branch it calls
gameDatabase.ClearStageData() and publishes the play style to the server query answer.
SaveGame.LoadWorldConfig reads with BinarySpanReader and TreeAttribute.FromBytes(ref BinarySpanReader).
OnBeginConfiguration logs a warning in read-only mode, passes !progArgs.Readonly as requireWrite to
ProbeOpenConnection, and skips repair mode and DatabaseUpgrader when read-only. The call to
gameDatabase.UpgradeToWriteAccess() is gone.
Version strings: CreatedGameVersion, LastSavedGameVersion (WillSave), ServerChunk.GameVersionCreated and
ServerMapRegion.createdGameVersion are "1.23.0-pre.1".
Staging tables. Format v2 saves gain stagechunk, stagemapchunk and stagemapregion. Dirty chunks, map
chunks and map regions written on unload (ServerSystemUnloadChunks.SaveDirtyUnloadedChunks and
SaveDirtyMapRegions) now go to the staging tables via SetStage*. Loads
(ServerSystemSupplyChunks.TryLoadChunkColumn, TryLoadMapChunk, TryLoadMapRegion) read the staging table
first and fall back to the main table. Each save pass (SaveAllDirtyMapRegions, SaveAllDirtyMapChunks,
SaveAllDirtyLoadedChunks) first moves staged entries into the main tables (MoveStage*, one transaction each).
LoadSaveGame clears the staging tables at start-up, so data unloaded after the last full save is discarded if
the server stops without saving (inferred intent: the main tables always hold a consistent save). A tool or mod
that reads chunk, mapchunk or mapregion directly may miss entries that are still staged; /db prune
(ForAllChunks) only walks the main table.
Read-only.GameDatabase.ReadOnly (public, set from requireWriteAccess) makes Vacuum, SetChunks,
SetMapChunks, SetMapRegions, SetStage*, MoveStage*, ClearStageData, Delete*, SetPlayerData and
StoreSaveGame(SaveGame, FastMemoryStream) silently do nothing. StoreSaveGame(SaveGame) and the backups are not
guarded. In read-only mode the base SQLiteDBConnection.OpenOrCreate skips CreateTablesIfNotExists, so a save
that 1.23 has never opened for writing has no staging tables, OnOpened leaves the getStage*Cmd commands null,
and GetStageChunk is not guarded (inferred: a NullReferenceException on the first chunk load).
GameDatabase is sealed; its private field conn is now connection and every call goes through the
private openedConnection property, which throws InvalidOperationException before open or after dispose.
CloseConnection() is public. OpenConnection throws ArgumentOutOfRangeException for an unknown database
version. GetSaveGame() returns null if no connection is open.
Player data table.CreateTablesIfNotExists now creates playerdata (playeruid TEXT PRIMARY KEY, data BLOB)
and calls TryMigrate(), which rebuilds an old table (with the playerid column) keeping the row with the lowest
playerid per UID; duplicate entries are dropped. SetPlayerData is a single prepared INSERT OR REPLACE.
Prepared commands.SQLiteDbConnectionv2 prepares its player-data, game-data and map-region commands once in
OnOpened. StoreGameData no longer opens its own transaction (it still takes transactionLock).
ChunkExists(ulong, DbCommand) and GetChunk(ulong, DbCommand) no longer dispose the command passed in (1.22.7’s
using DbCommand cmd = preparedCmd; disposed the prepared command). BackupPartial reads inside one transaction
with its own commands and writes in batches.
Member (1.22.7)
1.23.0-pre.1
What to do
GameDatabase (public class)
sealed
Wrap it instead of subclassing
GameDatabase.conn (private)
connection, accessed through openedConnection
Update reflection
GameDatabase.CloseConnection() (internal)
public
Call directly
GameDatabase.UpgradeToWriteAccess() (public)
removed
Open with requireWriteAccess: true
IGameDbConnection.UpgradeToWriteAccess()
removed (also from SQLiteDbConnectionv1, SQLiteDbConnectionv2)
Block entities.WorldChunk.BlockEntities is a Dictionary<int, BlockEntity> keyed by
BlockPos.ToIndex3d() and is created on first read (see “Block accessors, the world map and chunk data”). ServerChunk works
on the blockEntities field directly and treats null as empty: RemoveEntitiesAndBlockEntities,
GetBlockEntitiesPackets, FastSerializeBlockEntities* and the packet builder skip or count zero, the unpack
path creates the dictionary before filling it, and ClearAll now sets it to null inside packUnpackLock.
FastSerializeBlockEntitiesCount now always writes the count field, also when it is zero. Iterations in
ServerSystemSupplyChunks (chunk-loaded block entity init) and WorldAPI (chunk column unload) changed to
KeyValuePair<int, BlockEntity>. A transpiler or postfix that indexed by BlockPos breaks.
Unpacking.ServerChunk unpacks entities, block entities and decors with BinarySpanReader and calls
Entity.FromBytes(ref BinarySpanReader, bool, ...) and TreeAttribute.FromBytes(ref BinarySpanReader) (API
chapter). A corrupted block entity header now continues (same effect as the old goto).
ServerChunkTrimmed (new public [ProtoContract] class) holds only protobuf members 12
(GameVersionCreated), 17 (BlocksPlaced) and 18 (BlocksRemoved) of a ServerChunk. The /db prune command
deserialises it instead of a full ServerChunk.
Prune (ServerSystemSupplyChunkCommands.prune, private). All work, including collecting land-claim columns,
moved into the background delegate. Claims are pre-expanded into a set of kept columns instead of a rectangle test
per chunk. A chunk that fails to deserialise is logged and skipped (1.22.7 rethrew). Progress is logged.
Sending (ServerSystemSendChunks, internal). Chunk generation requests are now throttled per client with the
new public field ConnectedClient.recentChunkRequestsCount: sendAndEnqueueChunks decrements it by one each call
and zeroes it for creative and spectator players; loadSendableChunksAtCurrentRadius scales the per-tick request
budget down once the count exceeds eight budgets, collects missing columns in the new workingSendList and queues
them under one requestedChunkColumnsLock. A missing column now counts as “sent or requested” only when
AutoGenerateChunks is on, and counts even beyond the request budget. When the budget is throttled to zero the
method returns 0, which the caller reads as “radius done” and advances CurrentChunkSentRadius (inferred side
effect).
Generation and loading (ServerSystemSupplyChunks). The “created before this version” test for map region
upgrades compares with "1.23.0" (was "1.22.7"). The start-up progress log counts completed columns returned by
CleanupRequestsQueue() instead of loadedChunks.Count.
ServerWorldMap adds GetChunk(FastBlockPos) and GetBlockEntity(FastBlockPos) overrides (see “Block accessors, the world map and chunk data”).
Worldgen accessor.WorldgenWorldAccessor (internal) adds SeedWorldgen, CollisionScene,
TriggerDidPlaceBlock, TriggerDidBreakBlock (forwarded) and GetTotalUnpausedTimeMs() / GetTotalUptimeMs(),
which throw NotImplementedException. GetRecipeRegistry(string) became GetCustomRegistry(string) and still
throws.
Member (1.22.7)
1.23.0-pre.1
What to do
ServerChunk use of BlockEntities (Dictionary<BlockPos, BlockEntity>)
blockEntities (Dictionary<int, BlockEntity>, may be null)
Ban and whitelist storage.PlayerDataManager keeps bans and whitelist entries in
Dictionary<string, PlayerEntry> keyed by player UID. Name-based matching and the UID back-fill that
GetPlayerBan / GetPlayerWhitelist did are gone, so entries without a UID no longer match anyone. Loading uses
Dictionary.Add(entry.PlayerUID, entry), so a file entry with a null or duplicate UID throws while
PlayerDataManager.Load() runs (inferred: not traced how start-up handles it).
Serializer.playerdata.json, playergroups.json, playersbanned.json and playerswhitelisted.json are
now read and written with JsonUtil.SerializeFastToFile / DeserializeFastFromFile (System.Text.Json with
IncludeFields), not Newtonsoft. Newtonsoft attributes on these types no longer decide what is saved:
ServerPlayerData.PermaPrivileges and DeniedPrivileges (internal) gained [JsonInclude], and the
PlayerGroupMemberships alias gained [System.Text.Json.Serialization.JsonIgnore]. A mod that relies on
Newtonsoft attributes, settings or converters for these files must check the new output. An empty file now loads
as an empty list instead of stopping the server.
Dates.FirstJoinDate and LastJoinDate are written as ISO 8601 ("O"). On load, TryLoadISODateTimes
rewrites any old value containing a space (including LastCharacterSelectionDate), parsing with the current
culture, then en-US for AM/PM strings, then en-GB, else now.
ServerWorldPlayerData. On the server, DesiredViewDistance is never written any more (it stays 0); use
LastApprovedViewDistance or Viewdistance, which is now clamped to the server maximum. The
LastApprovedViewDistance setter throws InvalidOperationException (in 1.22.7 it recursed into itself).
PreviousPickingRange has [DefaultValue(100)]. Inventories and the player entity are read with
BinarySpanReader.
ServerPlayer.Disconnect(string) renamed its parameter to logMessage, and a new virtual
Disconnect(string logMessage, string playerMessage) and SendPlayerRedirect(string host, string name) were added
(IServerPlayer, API chapter); ServerConsolePlayer overrides both Disconnects as no-ops. The explicit
IPlayer.IsInInteractionRangeOf(BlockPos, float) is replaced by public
IsInInteractionRangeOf(FastBlockPos, float slack = 0.25f), and the internal static
isInInteractionRangeOf(IPlayer, IBlockAccessor, FastBlockPos, float) takes a FastBlockPos.
ServerPlayerInventoryManager. The private field server is gone; the constructor is now a primary
constructor and the ServerMain lives in the compiler-generated field <server>P. DropItem(ItemSlot, bool fullStack) has no default for fullStack and returns false if the player has no "ground" inventory.
OnPlayerDisconnect closes and removes non-player inventories in one pass.
ServerSystemInventory (internal). HandleSelectedHotbarSlot also calls
InventoryPlayerHotbar.UpdateOffhandHungerPenalty(player). HandleCreateItemstack only fills a creative slot if
slot.CanHold(...) accepts the stack. HandleHandInteraction caps held-item use catch-up at 100 steps (was 5000)
and its range checks follow the anti-abuse rules below.
The anti-abuse monitor now counts placements as well as breaks, adds a slow window, and every interaction check reads
ServerConfig.RuntimeAntiAbuse: at LogOnly it writes to the audit log and lets the action through, at Basic or
Pedantic it also reverts or rejects. Because the default became Auto, a public dedicated server (whitelist off, no
password) now runs at Basic; 1.22.7 servers mostly ran with it Off.
PlayerAntiAbuseMonitor. It subscribes to EventManager.DidPlaceBlock as well as DidBreakBlock, each calling
PlayerBlockBreaks.RecordPlaceBreak(ElapsedMs, ElapsedMinutes). OnServerTick (every second) does nothing when
RuntimeAntiAbuse is Off; it skips players with gamemode or controlserver; once a minute it checks the slow
window (AntiAbuseTriggerOnBlockBreakPlaceCountSlow events within AntiAbuseTriggerOnDurationSlowMin minutes,
moderatePlayerSlow), otherwise the burst window (moderatePlayer(uid, limit)). Both log to the audit log and ban
and kick only when ShouldModerate(); in 1.22.7 any level above Off banned. RemoveInactivePlayers replaces the
inline cleanup. The handlers index BlockEventsByPlayer[uid] directly, so a mod that calls the new
TriggerDidPlaceBlock / TriggerDidBreakBlock for a player who has not joined gets a KeyNotFoundException
(inferred), and mod-triggered placements count towards the ban threshold.
Block place and break (ServerSystemBlockSimulation.TryModifyBlockInWorld, private). The range check uses
IsInInteractionRangeOf(pos) with the default slack of 0.25 (was 0.7) and no longer exempts players with the
pickingrange privilege (their picking range still counts through PickingRange). A new check rejects a
placement whose supporting block, on the clicked face, is air. Only mode 0 (break) and 1 (place) are handled;
any other mode returns false. The block-place branch was restructured (inverted if), which changes the IL a
transpiler sees.
Block interaction (HandleBlockInteract): range slack is the default 0.25 (was 0); catch-up loops for
step, stop and cancel are capped at 100 steps with a warning (new internal const
ServerSystemBlockSimulation.InteractStepsCatchupLimit, though the loops use the literal). HandleBlockEntityPacket
calls the new BlockEntity.OnReceivedClientPacket(IServerPlayer, int, SerializedData, ref CachedAccessPerms) and then
the old byte[] overload (API chapter).
Held-item use (ServerSystemInventory.HandleHandInteraction): block and entity range are checked separately;
a held item whose collectible attributes have handUseAntigriefCheck: true used on an air position is logged and,
when moderating, rejected with the slots resent.
Entity interaction (ServerSystemEntitySimulation.HandleEntityInteraction): out-of-range is logged, and only
returns when moderating.
Block logger.ServerSystemBlockLogger.DidPlaceBLock is renamed DidPlaceBlock. Break lines now end with
" using <code> TT:<tier>" and the item’s buffs attribute values when the held item is a tool (new private
static GetToolAndBuffInfo(ItemStack)), which matters to anything that parses the build log.
The spawner’s hook points moved. OnTrySpawnGroupNearOffthread is gone. OnTrySpawnEntity no longer runs on the
main thread in EntitySpawnerResult.Spawn: it runs in ServerSystemEntitySpawner.TrySpawnSomethingAt_offthrad,
which is on the dedicated spawner thread unless the server runs with reduced threads, once per candidate position and
before CanSpawnAt_offthread. The position it receives is the candidate block’s centre
(spawnPosition.ToVec3d().Add(0.5, 0.005, 0.5)), not the final spawn position, and handlers get the shared
server.blockAccessor from that thread. A handler that swaps the ref EntityProperties now changes the type that
CanSpawnAt_offthread tests. A new OnEntityGroupSpawning(Entity[] spawningEntities, long herdId) fires on the
main thread after a group’s entities are created and queued in DelayedSpawnQueue (so they are not yet in the world);
it also fires with an empty array when none passed CheckCanSpawnAt.
Herd ids are drawn once per TrySpawnSomethingAt_offthrad call (was once per Spawn), consumed even when
nothing spawns, and shared by every group that call finds (inferred from the code: the loop does not return after
queueing a group).
SpawnOppurtunity (class) is now the struct SpawnOpportunity with HerdId, OriginalType and a
constructor. EntitySpawnerResult.DoSpawn(...) returns the created Entity and uses each opportunity’s own
HerdId and OriginalType.
Group size rounding uses GameMath.RoundRandom(rand, val); the LCGRandom for spawn conditions is seeded with
SeedWorldgen.
PhysicsManager.PrepareEntitySpawns now loops over clientCount * 3 position entries; 1.22.7 stopped at
clientCount, so with several players only the first third were tested when deciding who receives a new
entity. DoWork asks entity.IsControlledByServer(mountableSupplier) (new virtual on Entity, API chapter)
instead of testing for a live player controller inline; override it to take over control of a mount.
EntityPosExtensions.maxMovePerPacket (private const) is now public MaxMovePerPacket (still 128).
New events on IServerEventAPI (API chapter); the engine itself does not raise the schematic events
The game-world-save trigger in ServerEventManager no longer throws when a static method is registered while the frame
profiler is on (val.Target?.ToString() ?? val.Method.ToString()). DidPlaceBlock and DidBreakBlock are raised as
before from ServerSystemBlockSimulation.HandleBlockPlaceOrBreak, and now also by any caller of
ServerMain.TriggerDidPlaceBlock / TriggerDidBreakBlock.
/player <name> grant|revoke|deny|removedeny <privilege> (CmdPlayer). The new private static
canModifyProtectedPrivileges(Caller, string, string, string, out TextCommandResult) refuses root always and
controlserver unless the caller has root, with an audit line. grantPrivilege removes a denial first
(DeniedPrivileges.Remove); if the player’s role then already grants the privilege it stops there and notifies
the target, where 1.22.7 also added it as a permanent privilege. All four skip the chat notice when you target
yourself and log with format arguments instead of interpolation.
/role <role> spawnpoint set (OnSpawnpointSetCmd) rejects positions outside the world.
/whitelist add|remove, /player <name> whitelist and /list banned (CmdGlobalList, internal)
use the UID dictionaries.
/debug (CmdDebug). helddurability, heldtemperature, heldcoattr and heldstattr and their private
handlers (getSetCollectibleAttr, getSetItemstackAttr, getSetItemStackAttr) moved to VSEssentials
(ModSystemHeldCommands, base game mods chapter), which also adds /heldname and /helddesc. /debug octagonpoints
uses LastApprovedViewDistance.
/entity wipeall and its private WipeAllHandler and entityTypeMatches are removed; nothing in the engine
or the base game sources replaces them.
/info seed returns SeedWorldgen; new /info seedsh returns Seed.
/serverconfig (CmdServerConfig, internal). Setting ServerName, ServerDescription, MaxClients or
removing the password refreshes the server query answer. /serverconfig password <word> casts its string argument
to bool after storing it, which throws (inferred: the password is still set, the query answer is not updated and
the command reports an error). /serverconfig modwhitelist add seeds an empty ModIdWhiteList with game,
survival and creative before adding, and refuses duplicates.
/allowlan (CmdToggleAllowLan) recomputes RuntimeAntiAbuse after opening or closing the LAN socket.
/execute as (CmdExecuteAs) builds its caller with Caller.FromEntity(entity, privileges), which now also
sets Caller.Pos. Player chat commands go through Caller.FromPlayer(player, groupId) in ChatCommandApi.Execute
(the client overload now also gets a Pos). See the API chapter for Caller.
PlayerRole, CmdGlobalList, CmdStats, CmdTime, CmdDebug and ServerSystemSupplyChunkCommands now format
with the runtime’s System.Runtime.CompilerServices.InlineArrayN<object> instead of the compiler-generated
<>y__InlineArrayN<object>, which changes the generic type tokens a transpiler would match.
ServerSystemRemapperAssistant.OnCmdApplyall renamed locals and deconstructs the pair (new locals).
ServerSystemModHandler calls ModLoader.LoadMods(EnumAppSide.Server, ...) (see Mods). ServerAPI.ServerIp
reads NetServer.ListenIp (see Networking). ServerCoreAPI.PlatformUtils is new (API chapter).
ServerSystemCalendar, ServerSystemWorldAmbient (also reads with BinarySpanReader), ServerSystemUnloadChunks,
ServerSystemEntitySimulation, PhysicsManager, ServerWorldMap and ServerMapRegion otherwise only changed send
call sites or version strings. ServerProgram and CmdStats version strings read 1.23.0-pre.1
(ServerProgramArgs help heading: 1.23.0). GameCalendar gained GetSeason, GetSeasonRel and
GetHemisphere overloads taking (double x, double z); the BlockPos forms forward to them and no longer throw for
a null position (API chapter).
ConcurrentTagRegistryFast gains public TagSetFast CreateTagSet(params ReadOnlySpan<string> tags). Unlike
TryCreateTagSet, it throws for a tag that is not registered. It takes the read lock unless the registry has been
locked.
IncrementalBackoff (internal struct, new) is a retry interval with IncreaseInterval(float factor = 1.5f),
DecreaseInterval(float factor = 2/3), ResetInterval() and an implicit conversion to TimeSpan. The server
heartbeat and the client’s multiplayer screen use it.
AssemblyVersion and AssemblyFileVersion are 1.23.0.0 and 1.23.0.
References: ICSharpCode.SharpZipLib is gone (the only user was ModContainer), and the game no longer ships the
DLL (see the bundled libraries chapter). No new assembly references; zip work uses System.IO.Compression from the
runtime.
New embedded resource AssetSchemas.DialogueAsset.schema.json (see “Assets and origins”).
Compiler-generated types, which matter only to reflection on their names:
The <>y__InlineArray4, 5, 6 and 8 structs are gone. Code that builds Path.Combine and string.Format
argument spans now uses the runtime’s System.Runtime.CompilerServices.InlineArrayN<T>. This changes the generic
type arguments in the IL of CleanInstallCheck, ModContainer.LoadModInfo and similar methods.
New <>z__ReadOnlyArray<T> and <>z__ReadOnlySingleElementList<T> back collection expressions, for example in
ModCompilationContext and AssetSchemaExporter.
The source-generated regex type (GetHtmlTagRegex) is unchanged in logic. Its generated class name changed hash,
and it is now made by System.Text.RegularExpressions.Generator 10.0.14 (was 10.0.13).
The game version is inlined as a constant in several places, so it changed in their IL:
CleanInstallCheck looks for assets/version-1.23.0-pre.1.txt;
EntityTypeNet passes "1.23.0-pre.1" to AnimationMetaData.FromBytes;
AssetSchemaExporter stamps and compares "1.23.0-pre.1".
Cosmetic or near-cosmetic, no action unless a transpiler counts IL:
File
Change
IL effect
InventoryPlayerBackpacks
one internal constant added
none
CleanInstallCheck
version string and inline-array type
generic arguments change
ModLoader.DisableMods
Count() became Count
one call fewer
ModLoader (the FormatException catch)
throw ex became throw
stack trace is now preserved
ModContainer (the ReflectionTypeLoadException handling)
pattern variable exr
adds a local
PlayerInventoryManager
nullable annotations, expression-bodied members, Find rewritten with LINQ
locals, calls and closures change throughout; re-derive any transpiler
A complete, mechanical list of every type and member of VintagestoryLib that was added, removed or changed between
1.22.7 and 1.23.0-pre.1, private members included, taken from the compiled metadata of both assemblies.
Compiler-generated types and members (closures, state machines, inline arrays, backing fields) are left out. Search it
for the type or member you patch.
How to read the tables:
Change.added and removed are whole members. changed pairs an old signature with its new one (a changed
type, parameter, return type, accessibility, modifier or [Obsolete] message). overload added is a new overload of
a method that kept its old overloads. type added, type removed and type changed describe the type itself (kind,
sealing, base types).
Signatures are written in C# style with namespaces left off. = … marks a parameter with a default value.
Constructors are written with the type’s name. Explicit interface implementations keep their interface prefix.
Reach.public means a mod can use the member without reflection: a public or protected member of a public
type. internal means anything else (private, internal, or any member of a non-public type); you need reflection,
Harmony or a publicised reference to reach it. public → internal marks a member or type that lost its public
reach.
A member listed under its declaring type only. Inherited members are not repeated on derived types.
public bool TryGetCustomTexture(TCTCache vars, int localFace, int worldFace, float[] tfMatrix, MeshData sourceMesh, int faceIndex, int shapeRotationSteps, out CustomTextureResult result)
public bool TryGetCustomTexture(TCTCache vars, int localFace, int worldFace, float[] tfMatrix, MeshData sourceMesh, int faceIndex, int shapeRotationSteps, out CustomTextureResult cTexResult)
public bool IsInInteractionRangeOf(FastBlockPos blockPos, float slack = …)
public
removed
private bool Vintagestory.API.Common.IPlayer.IsInInteractionRangeOf(BlockPos blockPos, float slack = …) [Obsolete: This signature will change in 1.23. Avoid it for now.]
public bool GetOrInsertTexture(AssetLocationAndSource loc, out int textureSubId, out TextureAtlasPosition texPos, CreateTextureDelegate onCreate = …, float alphaTest = …)
public bool GetOrInsertTexture(AssetLocationAndSource path, out int textureSubId, out TextureAtlasPosition texPos, CreateTextureDelegate onCreate = …, float alphaTest = …)
public
added
-
private bool GetOrInsertTextureInternal(AssetLocationAndSource loc, out int textureSubId, out TextureAtlasPosition texPos, CreateTextureDelegate onCreate = …, float alphaTest = …, bool addReference = …)
internal
added
-
public bool InsertTextureOrAddReference(CompositeTexture ct, out int textureSubId, out TextureAtlasPosition texPos, float alphaTest = …)
public
added
-
public bool InsertTextureOrAddReference(AssetLocation path, out int textureSubId, out TextureAtlasPosition texPos, CreateTextureDelegate onCreate = …, float alphaTest = …)
public
added
-
public bool InsertTextureOrAddReference(AssetLocationAndSource path, out int textureSubId, out TextureAtlasPosition texPos, CreateTextureDelegate onCreate = …, float alphaTest = …)
public
added
-
public void ReleaseTextureReference(AssetLocation loc)
public Block GetBlock(FastBlockPos pos, int layer)
public
overload added
-
public BlockEntity GetBlockEntity(FastBlockPos position)
public
overload added
-
public T GetBlockEntity<T>(FastBlockPos position)
public
changed
public virtual int GetBlockId(BlockPos pos) [Obsolete: Calling code should specify the appropriate BlockLayersAccess. Default is fine in many cases, but BlockLayersAccess.Fluids should be used to check for water, lake ice or lava reliably]
public virtual int GetBlockId(BlockPos pos)
public
changed
public virtual int GetBlockId(int posX, int posY, int posZ) [Obsolete: Calling code should specify the appropriate BlockLayersAccess. Default is fine in many cases, but BlockLayersAccess.Fluids should be used to check for water, lake ice or lava reliably]
public virtual int GetBlockId(int posX, int posY, int posZ)
public
overload added
-
public virtual int GetBlockId(FastBlockPos pos)
public
overload added
-
public int GetBlockId(FastBlockPos pos, int layer)
public
overload added
-
public IWorldChunk GetChunkAtBlockPos(FastBlockPos pos)
public virtual void Disconnect(string logMessage, string playerMessage)
public
changed
internal static bool isInInteractionRangeOf(IPlayer player, IBlockAccessor blockAccessor, BlockPos blockPos, float slack) [Obsolete: This signature will change in 1.23. Avoid it for now.]
public bool IsInInteractionRangeOf(FastBlockPos blockPos, float slack = …)
public
added
-
public void SendPlayerRedirect(string host, string name)
public
removed
private bool Vintagestory.API.Common.IPlayer.IsInInteractionRangeOf(BlockPos blockPos, float slack = …) [Obsolete: This signature will change in 1.23. Avoid it for now.]