Modding:Modding API Updates

This page was last verified for Vintage Story version 1.19.8.

The Vintage Story API is responsible for almost all functionality for modding the game. This page will list changes made to the API in each version, taken directly from the VS News page. Changes will be sectioned by content, code, or other, based on what type of mod they mostly affect.

Some points may contain additional information on how this will affect mods.

This log starts at version 1.19.0, and changes from before then are not listed. Release candidate versions (suffixed with rc) are not listed until they are released as stable versions.

How to Utilise This Page for Modders

This page gives updates on all API updates for code and content modders. When updating a mod, it is recommended to find the version your mod was released for in this list. From there, scrolling up will display all the changes made to the API since that version. If your mod uses any of those API features, it is recommended to test them. This will give you a good idea of what parts of a mod may need updating for newer versions.

1.19

1.19.8

There are no API changes for this version.

1.19.6/1.19.7

Code

• API Fixed: RegisterEventBusListener() delegates called twice in some cases

1.19.5

Content

• Api Tweak: Items/Blocks can now define an attribute "inBarrelShape" to determine their shape inside a barrel

Code

• Api Fixed: WorldAPI RegionMapSizeX would return a size off by one since game version 1.12.9. Affected methods are MapRegionIndex2D, MapRegionPosFromIndex2D, MapRegionIndex2DByBlockPos
• Api Fixed: Chatcommands with multiple `WithPreCondition` or a pre-condition and `RequiresPlayer` would over-write each other. Now all pre-conditions are checked and if one pre-condition returns EnumCommandStatus.Error it won't process the command further.

Other

• Api Tweak: Don't crash on invalid GroundStack

1.19.4

Content

• Tweak: Added a new attachment point on the seraph model for off-hand animations
• Tweak: New and updated stackrandomizers are available to allow random loot to be placed in containers in schematics; and these randomizers can be modded to add or change loot in vanilla ruins: for details see the randomizers in assets/survival/itemtypes/meta
• Tweak: If an item specifies a renderVariant, and the shape cannot be found, log an error instead of crashing
• Tweak: Modded spears should now include behavior "AnimationAuthoritative", see vanilla spear.json for an example
• Tweak: Added entity property fallDamageMultiplier
• Notice: Entity boolean property fallDamage will become obsolete in v1.20 and removed in v1.21. Use fallDamageMultiplier: 0.0 instead
• Fixed: Block patches with NearSeaWater placement now detect salt water properly
• Fixed: Incorrect door and chest took on wrong appearance when animated in heavily modded games, due to multiple texture atlas creation, when using default texture atlas sizes
• Fixed: Microblocks not allowing 255 materials

Code

• Additional minor tweaks relevant only to coded mods:
  • KeyConfiguration used for hotkeys can now also represent a mouse button; mouse buttons are treated like keyboard keys with keycodes 240-247
  • For AITasks, the EntityPartitioning system is now divided more logically into Creatures and Inanimate entities, use EnumEntitySearchType to specify which
  • For all string IndexOf(), StartsWith() or EndsWith() operations on strings representing game internal elements, for example AssetLocation, texture codes and other dictionary keys or anything found in JSON code, StringComparison.Ordinal should be used for culture independence.  See .NET Best Practice Guide.  Vintagestory.API.Util now provides helper methods string.IndexOfOrdinal(), string.StartsWithOrdinal() and string.EndsWithOrdinal() which you can use; and for AssetLocations, ordinal comparison is built-in to new convenience method AssetLocation.PathStartsWith()
  • Mods can access and change climbUpSpeed and climbDownSpeed in an entity's BehaviorControlledPhysics
  • Marked UsingHeldItemTransformBefore/After as obsolete
  • Exposed GetRecipeRegistry() in IWorldAccessor
  • BlockEntity.GetBlockInfo() exceptions now trapped and logged, a simple error line is shown in the Block Info HUD
  • Exceptions thrown by ticking a BlockEntity are now logged with position of entity and type; override BlockEntity.TickingExceptionHandler to change this behavior
  • Exceptions thrown by BlockEntity.FromTreeAttributes() are now logged with position of entity and type
  • Any mod directly accessing BlockEntityMicroBlock.sideAlmostSolid or .sidecenterSolid should re-compile for 1.19.4 (no actual code change in the mod should normally be required, but the field type changed, pull latest VSSurvivalMod source from GitHub)
  • Notice: For coded mods using native binaries (.dll in Windows) in a /native folder, these will now not get loaded automatically (they would produce 'Bad IL format' errors at loading time anyhow). Applies to native binaries representing either libraries or a mod's own code not written in C#. Mods needing to load native binaries should instead write their own short DllImportResolver method [example] to locate their native binaries properly for each platform, and also include a static call to set that DllImportResolver [example line of code]

Other

• Tweak: Missing dependencies now listed in the mod manager
• Tweak: Log an error if HeldRightReadyAnimation and HeldRightTpIdleAnimation for an item are set to the same animation

1.19.2/1.19.3

Code

• API Fixed: DidPlaceBlock() not called on the last block in the stack

1.19.1

There are no API changes for this version.

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