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.20

1.20.1

No API changes for this version.

1.20.0

See all update notes here. API changes are listed below.

With the 1.20 release, the inbuilt modmaker program has been updated, and there now exists a JSON property reference page. It is recommended that you take a look at this!

Content

• Feature: Allow json file inheritance for blocks, items and entities using property "inheritFrom", example: assets/survival/blocktypes/wood/woodtyped/roughhewnfence-fsnow.json
• Feature: Max animated elements cap is now 230 but up to 1000 can be set via settings (Technical info: Now sending animation shader data via UBOs instead of uniforms) I had to remove the 4x3 matrix optimization because UBOs seem to pad non 4-int rows and thus break the matrix stride. On the bright side this change should actually improve performance by a little bit by not uploading unused transformation matrixes (uploads now only until the necessary jointid instead of GlobalConstants.MaxAnimatedElements
• Feature: Modmaker Improvements
  • Now asks the user if they wish to ignore the shapes folder when looking for file differences. The shapes folder contains nearly 4,000 relatively large files, it takes up a large portion of time when searching for file differences. However, many mods and modders do not have a need for this. Ignoring the shapes folder cut down execution time by an average of 65% (from 9055ms avg. to 3122ms avg.).
  • Adds a function to the modmaker which restores all vanilla assets in their unmodified, vanilla state
  • Add ability to re-export all the JSON assets in a standardized way. When editing vanilla files in Notepad++, nearly every property is highlighted in red due to it not using "s for property names, and similarly with Visual Studio. By importing each json file and immediately exporting them, it reorganises them in a much neater, IDE-friendly manner
  • Adds the ability to delete the temporary folders created by the mod maker. In case any one has any issues with the mod maker, they can run this and it may resolve them. Saves them from manually finding and deleting temp folders
  • Makes the mod maker compare files based on their JSON properties. Although this has a minor performance impact, it allows the ability to validate all the JSON files to ensure they are valid, as well as allows the modder to use different JSON formats if they so wish.
• Feature: New entity type property: "behaviorConfigs". Can be used to pre-define entity behavior configs, which get applied to both server and client behaviors, eliminating the need to write configs twice.
• Feature: Can now also add hair elements to the seraph that are only shown when certain clothing items are worn. Example implementation: assets\game\shapes\entity\humanoid\seraphskinparts\hair-extra\braidedup.json
• Feature: Can now define IgnoreElements for block/item/entity shapes
• Feature: For semi-submerged boats, can use EntityBehaviorHideWaterSurface to not render water inside the boat using a flat plane of hiding elements in the boat model file. See also boat.json
• Feature: Can now use step-parented shape overlays for entities. Example: Male elk
• Feature: Added Multiple collision boxes entity behavior. Currently only available as an upgrade to the PassivePhysics entity behavior.
• Feature: Added new tool types in EnumTool
• Refactor: Removed property entity.GearInventory. Now replaced by EntityBehaviorContainer.
• Refactor: Removed EntitySkinnableShapeRenderer. Now replaced by EntityBehaviorTexturedClothing
• Refactor: Rename block clutter property randomizeDimensions to randomizeYSize
• Refactor: Collectible.IsBackPack() is now obsolete. Use collectiblebehavior { name: "HeldBag" } instead
• Tweak: Add "withDrops" property to BehaviorTransformBreak
• Tweak: Can now use shape overlays for clothing
• Tweak: Allow TransitionableProperties (perishableProps in cooking pot recipes) with transition type "None"
• Tweak: Cooking recipes add support for "DirtyPotOutputQuantity" property
• Tweak: Can now add a "whenSwimming: true/false" condition to AI tasks
• Tweak: Made henbox more moddable
• Tweak: Add support beam behavior property "dropWhenBroken"
• Tweak: Can now set vertex flag bit 28 to 1 for liquids to have them rendered mostly opaque
• Feature: The Pathfinding system can now differentiate between types of creature and alter pathfinding behavior accordingly. Set via property aiCreatureType on the BehaviorTaskAI Config. See also enum file EnumAICreatureType
• Refactor: Seraph left hand attachment point was not at the same spot as the right hand one (seraph.json model file edit only)
• Refactor: Move out trader trade lists into separate files, but the integrated trade list method still works
• Tweak: Do not play the default idle animation on any creature if some other "BlendMode=Average" animation runs. To modders that add entities with animations: You will want to set your standard walk and run animations to BlendMode: "Average"
• Tweak: Allow custom names for clutter depending on used texture
• Tweak: Add ability to define multiple cooking recipe in one recipe json file
• Tweak: inheritFrom can now be applied recursively (an inherited file can also use inheritFrom)
• Tweak: Can now configure humanoidTraversalCost via json, example implementation in blocktypes/wood/table.json. Added high traversal cost for several blocks such as chairs and tables.
• Tweak: Don't crash game if there is a syntax error in a dialogue file
• Tweak: structures.json now allows to set a MaxBelowSealevel. So sealevel - MaxBelowSealevel is the max height the schematic is allowed to spawn. MaxBelowSealevel defaults to 20 if not specified
• Tweak: structures.json minGroupDistance was limited to 46_340 now it can up to 3_037_000_498 blocks Tweak: Add "MinSpawnDistance" support for structures/ruins. Lets you define a certain distance constraint from the spawnpoint
• Tweak: Allow mods to define their own worldproperties/block/metal.json instead of needing to patch the file
• Tweak: Allow BlockBehaviorHarvestable to have multiple drops
• Tweak: Cooking system - allow modded meal names - Meals can now be created through just json files.
• Fixed: BlockEntityGenericTypedContainer should not require BEBehaviorAnimatable

Code

• Refactor: Rename MultiBlockInteract.GetSounds to IMultiBlockInteract.MBGetSounds
• Refactor: Rename IClientWorldAccessor.Dimensions to IClientWorldAccessor.MiniDimensions
• Refactor: IMountableSeat.SuggestedAnimation now needs to return a AnimationMetaData instead of a string
• Refactor: Big rewrite in how entity inventories are coded. There is no longer a single placeholder entity.GearInventory field instead there is now a abstract class EntityBehaviorContainer that "container entity behaviors" can inherit from such as EntityBehaviorAntlerGrowth and the new EntityBehaviorDressable. This also necessitated the replacement of EntitySkinnableShapeRenderer by a new class EntityBehaviorTexturedClothing which inherits from EntityBehaviorContainer.
• Refactor: Clean up BEIngotMold and BEToolMold code
• Refactor: Entity.BodyYawLimits and EntityPlayer.BodyYawLimits and HeadYawLimits.HeadYawLimits are now of class AngleConstraint. Changed definition from min/max angle to center+range angle.
• Refactor: shape.SubclassForStepParenting() no longer prefixes a dash "-" to the texture codes
• Refactor: Block.ShouldPlayAmbientSound() is now obsolete, use GetAmbientsoundStrength() instead.
• Refactor: Add BlockPos argument to IDrawYAdjustable.AdjustYPosition()
• Refactor: Block.GetSounds(IBlockAccessor blockAccessor, BlockPos pos, ItemStack stack = null) is now Block.GetSounds(IBlockAccessor blockAccessor, BlockSelection blockSel, ItemStack stack = null)
• Refactor: Field InventoryBase.OnAcquireTransitionSpeed is now an event, i.e. use += to register to the event
• Refactor: Parts of BlockEntityContainer are now in a BE-agnostic class named "InWorldContainer", stored in the block entity field "container"
• Refactor: Rename IMountableSeat.CreateMountable() to IMountableSeat.GetMountable()
• Refactor: Rather major refactor of the player mounting system. Renamed IMountableSupplier to IMountable. The previous IMountable is now called IMountableSeat. The interface methods IMountableSupplier.IsMountedBy() and IMountableSupplier.IsBeingControlled() and are no longer required they are implemented by class extensions now. IMountableSupplier.MountPoints is now IMountable.Seats. Removed IMountableSupplier.GetMountOffset() and IMountable.MountPosition it is replaced by IMountableSeat.SeatPosition and IMountableSeat.RenderTransform(), which is a more intuitive, more concise and more powerful way of getting the player to the intended seating position, and with the right transforms.
• Refactor: Collectible.IsBackPack() is now obsolete. Use collectiblebehavior { name: "HeldBag" } instead
• Removed: EntityAgent.OnNoPath() and EntityBehavior.OnNoPath() method deleted they are not needed
• Tweak: Reserved characters for AssetLocation paths are listed in GlobalConstants.ReservedCharacterSequences (Detail: Textures only for now, as that is the main area where reserved characters should not be used. The game checks all mod filenames in the "textures/" path for these reserved characters at game startup, will throw an exception if found)
• Tweak: New particle property LightEmission
• Tweak: Most server side events are now more robust against crashing mods the event will continue to be executed on the remaining mods instead of stopping
• Tweak: Made IShaderProgram.AssetDomain available to mods
• Tweak: Clean up animation code related to loading the animator object. AnimationCache.InitManager() is now obsolete
• Tweak: new BlockFacing.HorizontalFromYaw() method to get facing from player yaw
• Tweak: Mainhand and offhand items can now apply any character stats via statModifier
• Tweak: Can now add a "whenSwimming: true/false" condition to AI tasks
• Tweak: Made henbox more moddable
• Tweak: Can now also associate sounds to an entity animation frame directly in the AnimationMetaData object
• Tweak: Made IMPPowered interface public
• Tweak: New ModSystem method: bool ShouldLoad(ICoreAPI api)
• Tweak: Added CollectibleObject.SetDurability()
• Tweak: entity.RenderColor is now an set-able property. Moved damage color overlay to BehaviorHealth.cs
• Tweak: Removed useless MeshData.AddVertexWithFlagsSkipTexture() which did not skip texture. :facepalm:
• Tweak: Simplified LinkTextComponent constructor to more compactly invoke link protocols, e.g. api.LinkProtocols["commandhandbook"].Invoke(new LinkTextComponent("commandhandbook://page-you-want-opened"));
• Fixed: Bug in meshdata.StepParentShape() related to animations caused a crash
• Fixed: shape.SubclassForStepParenting() did not subclass element names
• Fixed: Event AfterActiveSlotChanged simply crashing when triggered
• Fixed: Chat sub commands could not use a different privilege then the base command
• Feature: Add udp channels  similar to tcp channels using "api.Network.RegisterUdpChannel()"
• Feature: The Pathfinding system can now differentiate between types of creature and alter pathfinding behavior accordingly. Set via property aiCreatureType on the BehaviorTaskAI Config. See also enum file EnumAICreatureType
• Feature: Added Block.GetTraversalCost() method. Can be used to tell the pathfinding system how good or how bad a block is for traversal.
• Refactor: Make all internal fields and methods public in GameMain and ClientMain
• Refactor: Rewrite nametag handling. Code was a fat mess - all over the place. Now all in VSEssentials - BehaviorNameTag.cs
• Refactor: Moved engine coded SystemPlayerParticles to essentials mod ModSystemAmbientParticles
• Refactor: The event api.Event.OnTestBlockAccess, delegate argument "claimant" is now a ref, i.e. prefix it with "ref" in your code
• Tweak: BlockUpdate and DecorUpdate classes modified to accommodate subpositions (=cave art)
• Tweak: Added CollectibleBehavior.OnCreatedByCrafting
• Tweak: DiscDepositGenerator.absAvgQuantity is now public
• Tweak: Improve performance of SearchBlocks() by 2%
• Tweak: Added string<->AsseLocation conversion thing from Darkhekromant
• Tweak: Added interface ISearchTextProvider to provide custom text to the creative inventory search cache
• Tweak: Added EntityPlayer.HeadBobbingAmplitude property
• Tweak: Shape objects are now json serializable
• Tweak: Don't crash if a item/block is consumed/destroyed during OnHeldUseStep
• Tweak: Replaced ITextureAtlasAPI.LoadCompositeBitmap(AssetLocation path) with ITextureAtlasAPI.LoadCompositeBitmap(AssetLocationAndSource path)
• Tweak: BehaviorConversable now crashes if client side and server side dialogue path dont match
• Tweak: Readded Journal.DidDiscoverLore() method for a modder
• Tweak: Added damage type and damage tier to projectile for future use
• Tweak: IBlockAccessor.GetBlockRaw(x, y, z) method for use where x, y, z parameters are intentional and dimension-aware
• Tweak: Mark multiply tree as dirty after modifying totalDaysCooldownUntil
• Tweak: Moved IContainedMeshSource to getCollectibleInterface to support modded behaviors
• Fixed: If a custom InitWorldGenerator handler did throw an error subsequent handlers where skipped, now an exception is caught per handler
• Fixed: Number input gui element - up and down arrows not scaling well with the elementbounds
• Fixed: EntityPos.XYZFloat and EntityPos.XYZInt now take account of dimensions, same as EntityPos.XYZ
• Fixed: When patching files inside the worldgen folder (structures.json / storystructures.json , ...) those patches would be lost when running /wgen regen

Other

• Feature: Entity Activity System and Ingame UI Editor. Open with `.dev aedit`. More info on this feature in another update
• Feature: Spherical fog system. More info on this feature in another update
• Feature: Improved dimensions support in the game engine and API. More info on all this in a future post
• Refactor: Unified Seraph and Trader head sizes and accessories
• Tweak: Added .debug dumpanimstate [entity selector] and /debug dumpanimstate [entity selector]. Helpful for investigating incorrect blending of animations
• Tweak: Added command ".debug sound list" to print all active sounds
• Tweak: Improved `.debug self` output. now prints animation weights per shape element for the player. Only in debug builds. Unborked armor stand again (broke due to creature inventory rewrite). Fixed seraph animation derps while riding.
• Tweak: Avoid game crashing / throwing exceptions on a variety missing vanilla blocks (rusty gear, boilingwater, default worldgen blocks)
• Fixed: Rare(?) crashes reporting a full texture atlas. (Technical info: RenderItemStackToAtlas did not create a new atlas if all others were full)
• Fixed: Fundamental design flaw: entityPlayer.Pos.Yaw was always off by 90° and being corrected in various places throughout the engine where such corrections dont belong, such as Vec3d.AheadCopy, EntityPos.GetViewVector() and EntityPos.AheadCopy. Those methods would yield wrong values for non-player entities.
• Fixed: Lod0Shape not applying alt textures
• Fixed: Should fix exception thrown in some cases when creating a large explosion
• Fixed: 3D Decors attached to chiseled blocks turned into a flat texture
• Fixed: .reload textures causing all climate/season colored geometry to disappear when lots of textures are loaded, e.g. via mods
• Fixed: Flaw in the texture loading system that caused white borders around distant / shallow angle geometry
• Fixed: Extremely slow world loading when a large amount of errors are thrown while in developer mode
• Tweak: /debug expclang now alphabetically sorted
• Tweak: Can now time-freeze (prevents temperature and spoilage changes) collectibles via /debug heldstattr timeFrozen bool true
• Tweak: Added logging of exceptions thrown on instantiating registry objects
• Tweak: Add ability to runtime toggle aitasks and activity system. Disable via /worldconfigcreate bool runAiTasks false and /worldconfigcreate bool runAiActivities false
• Tweak: Hacky fixed sounds with a high range not having a high range, until we can rewrite the sound attenuation model
• Tweak: Taller Dialogue dialog. Already used answers now in a different color (non-persistent at the moment), fixed not able to use VTML
• Tweak: Tapestry can now be set to preserve as pristine on placing down schematics. User /giveblock tapestry-north{type:"forlorn1",preserve:true} 1
• Tweak: now all entity tasks, bows and spears have damage tiers for their projectiles

• Tweak: Add color blend mode OverlayCutout (dana PR)
• Tweak: Allow for more detailed Jam naming (pizza2004 PR)
• Tweak: Allow for modded buckets  (dana PR)
• Tweak: Don't hardcode barrel shapes  (dana PR)
• Tweak: Make barrels more moddable

• Tweak: Renamed 'The Seraph' music track, allowing it to be used in the music meta block for mods
• Tweak: expose waypoint data
• Tweak: entity.ServerPos and entity.Pos is now the same field, as we no longer need seperate positions on client and server removed in rc.8

• ModMaker Tweaks
  • Now allows for temporary assets to be created locally by copying an unmodified version of the game. Allows modmaking from pre-release versions
  • Removes hardcoding for not allowing dev or other versions.
  • Bug fixing for removing non-existent folders

• Fixed: Version 1 animation system not compatible with blender animations (thanks ketamine!)
• Fixed: Memory leak and heavy lag in some cases when using .tfedit
• Fixed: Entity variable of scope "entity" not working properly
• Fixed: Deleted almost all json duplicate keys in all assets
• Fixed: Block lighting bugs with lit schematics or lava
• Fixed: Raccoons harvesting berry bushes would only trigger the first harvestedStack.
• Fixed: Texture to index mapping now depends on file name

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.