Modding:Basic Entity

This page was last verified for Vintage Story version uknown.

We highly recommend to read about domains first. This tutorial will cover the basics of adding an entity to the game using JSON files. There is a full list of all properties which can be defined inside the json file

<translate>

This page is outdated.
Reason: A new system is being worked on to view JSON properties. Please use this page with caution, as it may not be up-to-date.
The content on this page is not up to date with the most recent game update. If you do wish to contribute, please request wiki edit access on the Discord.

Overview

In the code, these come from the fields listed with the "[JsonProperty]" attribute in EntityType.cs, plus the fields from the parent class RegistryObjectType.cs. The json parser is case insensitive, which is how the property names can have different capitalization in the code and in the table below.

</translate>

Property	Type	Default	Usage
json
Core (no byType available)
code	string	required	A unique identifier for the entity.
	A domain prefix will be added dynamically depending on the location of the file. Every mod and VintageStory itself have a unique prefix. For example the code rabbit turns into game:rabbit. The code identifier has to be unique inside its domain. In theory there could be equal identifiers with different domain prefixes. Find out more about Domains.
enabled	boolean	true	If the entity will be loaded or not. Can be used to temporarily remove the entity.
variantgroups	array of object	-	Allows you define multiple variants of the same entity.
(any) bytype	key: string; value: object	-	Allows different property values to be specified based on the variant code.
allowedVariants	array of strings	-	Used to trim unnecessary items generated by combined variants.
skipVariants	array of strings	-	Similar to allowedVariants, but instead skips the creation of listed variants rather than assigning which are allowed.
Common
class	string	"entity"	The entity class can add special functionalities for the entity.
	Can be used to add interaction to the entity or other special functionalities. Example uses are EntityItem and EntityPlayer.
habitat	string	"land"	There is sea, land, air, and underwater
hitboxsize	Vec2f	null	Convenience alias that sets both collisionBoxSize and selectionBoxSize.
collisionboxsize	Vec2f	{ x: 0.5, y: 0.5 }	The cuboid for collisions with other entities and blocks. The x value is the width and length of a square at the entity's feet. The y value is the height of the cuboid. Use .debug wireframe entity to see the box in game.
selectionboxsize	Vec2f	collisionboxsize	The cuboid for interacting with or attacking the entity. This is what would commonly be considered the entity's hitbox. The x value is the width and length of a square at the entity's feet. The y value is the height of the cuboid. Use .debug wireframe entity to see the box in game.
deadboxsize	Vec2f	null	Convenience alias that sets both deadCollisionBoxSize and deadSelectionBoxSize.
collisionboxsize	Vec2f	{ x: 0.25, y: 0.25 }	The cuboid for collisions with other entities and blocks when the entity is dead. The x value is the width and length of a square at the entity's feet. The y value is the height of the cuboid. Use .debug wireframe entity to see the box in game.
deadselectionboxsize	Vec2f	deadcollisionboxsize	The cuboid for interacting with or attacking the entity's carcass. The x value is the width and length of a square at the entity's feet. The y value is the height of the cuboid. Use .debug wireframe entity to see the box in game.
eyeheight	decimal number	0.1	Height of the eyes, measured from the bottom of the hitbox in meters. Used for camera angle and various other things.
swimmingeyeheight	decimal number	eyeheight	Replacement value for eyeheight while the entity is swimming.
weight	decimal number	25	This is unused by the base game. The documentation says it is the average weight of the entity in kilograms.
canclimb	boolean	false	Whether the entity can climb on ladders or other blocks which are climbable.
canclimbanywhere	boolean	false	Whether the entity can climb on any block, doesn't matter if it's a ladder or not. For example, this is set on locusts.
obsolete: falldamage	boolean	true	Whether the entity will take fall damage. Obsolete: set FallDamageMultipler to 0 instead.
falldamagemultiplier	decimal number	1.0	How much this creature is affected by fall damage. Setting this to 0 causes the entity to take no fall damage. Setting this to 2.0 causes it to take double fall damage.
climbtouchdistance	decimal number	0.5	Distance the entity can reach a block to climb on it.
rotatemodelonclimb	boolean	false	If true the entity model will be rotated to face the block its climbing on.
knockbackresistance	decimal number	0.0	The higher the number is the less knockback will be applied. Useful for heavy entities.
attributes	key: string, value: object	-	Custom Attributes associated with this entity.
	Extra attributes added to the entity. Those are final and cannot be modified. It's a good way to keep things organized and and modifiable. These can be used by behaviors or the entity class: attributes: { "attackPower": 10 },
behaviorconfigs	key: string, value: object	-	Adds fields to both the client and server behavior properties.
	The dictionary is indexed by the behavior code. If a corresponding behavior is found in the client or server configs, then the properties specified in this dictionary are merged with the client/server behavior properties. Any entries in this dictionary are ignored if they do not match a client or server behavior. For example, deer.json uses this to avoid having to copy the controlledphysics properties to both the client and server behavior definition: behaviorConfigs: { "controlledphysics": { "stepHeightByType": { "deer-pampas-*": 2.1251, "deer-pudu-*": 2.1251, "deer-redbrocket-*": 2.1251, "*": 3.1251 } }, ... }, client: { ... behaviors: [ ... { code: "controlledphysics" }, ... ], ... }, server: { ... behaviors: [ ... { code: "controlledphysics" }, ... ], ... },
sounds	key: string, value: string	-	Sounds of the entity, you can also add your own sounds and play them, but here is a list of default sounds used death, hurt, idle, jump, swim and eat
idlesoundchance	decimal number	0.3	How likely it is for the entity to play an idle sound.
idlesoundrange	decimal number	24	How far the idle sound played by the entity can be heard.
drops	array of object	-	The items that should drop from breaking this block.
	No drop By default an entity does not drop anything at all: drops: [], Drop You can also specify an item or block to drop. Therefore you need to define an ItemStack, with the given properties: Property Default Explanation type block Can either be block or item. code (required) - The complete code (can also include domain) of the item or block. lastdrop false If true and the quantity dropped is >=1 any subsequent drop in the list will be ignored. attributes - Tree Attributes that will be attached to the resulting itemstack. tool - If specified then given tool is required to break this block. quantity - (one) Determines the quantity of items which will be dropped. For example, if the entity should drop charcoalpile: drops: [ { type: "item", code: "charcoal" } ], You can also specify drop special itemstack if the entity is killed by certain tool, similar to Tallgrass which only drops something if it's mined by a knife: drops: [ { type: "item", code: "drygrass", tool: "knife" }, ], Chance drops Let's take a look at an example. This is the drop property of rock: drops: [ { type: "item", code: "stone-{rock}", quantity: { avg: 2.5, var: 0.5 } }, ] This will drop 2-3 blocks. avg: Stands for the default drop quantity. If var is 0 or not specified it will always drop the given average. var: How much the drop rate can vary. Meaning the drop rate can be avg - var at minimum and age + var at maximum. Furthermore you can also switch between different distribution modes using the dist property. Overview - Distribution modes Name Explanation uniform Select completely random numbers within avg-var until avg+var. triangle Select random numbers with numbers near avg being the most commonly selected ones, following a triangle curve. gaussian Select random numbers with numbers near avg being the most commonly selected ones, following a gaussian curve. narrowgaussian Select random numbers with numbers near avg being the most commonly selected ones, following a narrow gaussian curve. inversegaussian Select random numbers with numbers near avg being the least commonly selected ones, following an upside down gaussian curve. narrowinversegaussian Select random numbers with numbers near avg being the least commonly selected ones, following an upside down gaussian curve. invexp Select numbers in the form of avg + var, wheras low value of var are preferred. stronginvexp Select numbers in the form of avg + var, wheras low value of var are strongly preferred. strongerinvexp Select numbers in the form of avg + var, wheras low value of var are very strongly preferred. dirac Select completely random numbers within avg-var until avg+var only ONCE and then always 0. Multiple Drops Of course you can also define multiple drops at once. A Sapling for example can drop a sapling and a stick: drops: [ { type: "block", code: "sapling-{wood}", quantity: { avg: 0.02, var: 0 }, }, { type: "item", code: "stick", quantity: { avg: 0.02, var: 0 }, } ], Last Drop In order to add a special drop, which (if dropped) prevents all other drops, you can use the lastDrop property: drops: [ { type: "item", code: "stick", quantity: { avg: 0.2, var: 0 }, lastDrop: true }, { type: "item", code: "sapling", quantity: { avg: 1.25, var: 0 } } ], The entity will either drop a stick with a chance of 20% or an average of 1.25 saplings.
client: {
renderer	string	-	Name of there renderer system that draws this entity. Most entities use "shape". The valid values are: item dummy blockFalling shape playerShape echoChamber
texture	CompositeTexture		Sets the "all" entry in textures. The "all" entry overwrites all other textures in the shape.
base overlays alternates	Default example (player model): texture: { base: "entity/humanoid/player" } Using variantgroups (rock): texture: { base: "entity/humanoid/player-{type}" } Overlay texutre: texture: { base: "entity/humanoid/player-{type}", overlays: [ "entity/humanoid/player-{type}-overlay" ], } Random textures: texture: { base: "entity/humanoid/player-{type}", alternates: [ { base: "entity/humanoid/player-{type}2" }, { base: "entity/humanoid/player-{type}3"} ] } Random textures and overlays combined: texture: { base: "entity/humanoid/player-{type}", overlays: [ "entity/humanoid/player-{type}-overlay" ], alternates: [ { base: "entity/humanoid/player-{type}2", overlays: [ "entity/humanoid/player-{type}2-overlay" ] }, { base: "entity/humanoid/player-{type}3", overlays: [ "entity/humanoid/player-{type}3-overlay" ] } ] }
textures	key: string, value: CompositeTexture		Can be used to replace specific textures of the shape.
base overlays alternates	Replace arrow texture of the shape, the stick texture remains untouched: textures: { "arrow": { base: "entity/arrow/stone" } }
shape	CompositeShape	-	The shape of the entity.
base			The path to the shape json file, the base dir is assets/shapes/. shape: { base: "entity/arrow" }
glowlevel	0 ... 255	0	Causes the entity to visually glow if Bloom is enabled.
size	decimal number	1	Can be used to scale the entity up or down.
sizegrowthfactor	decimal number	0	The rate at which the entity's size grows with age - used for chicks and other small baby animals.
pitchstep	boolean	true	Makes entities pitch forward and backwards when stepping. This is usually left as the default, except for humanoid entities where most set it to false.
behaviors	array of object		Client side entity behaviors.
animations	array of AnimationMetaData		WIP
code	string		The identifier of the animation.
attributes	key: string, value: object	-	Custom attributes that can be used for the animation. Valid vanilla attributes are: damageAtFrame (float) soundAtFrame (float) authorative (bool)
animation	string		The animation code identifier to play.
weight	decimal number	1.0	Animations with a high weight value will be prioritized over the other animations when the animations are combined. For example if the player aims with a bow while jumping around, the aiming animation has a higher weight (for the upper body) so the jumping animation will be reduced.
elementweight	key: string, value: decimal number		Allows you to specify a weight for each element individually.
animationspeed	decimal number	1.0	The speed of the animation.
mulwithwalkspeed	boolean	false	Whether the animation speed should be multiplied by the entity's current movement speed.
easeinspeed	decimal number	10	The ease in affects the weight of the animation, so that it starts off with weak strength (the animation only slightly changes the entity shape) and gradually goes to nearly full strength. The ease in only affects the strength of the animation, not the speed the animation plays at. With easeinspeed=1, it takes roughly 0.7 seconds for the animation to get to half strength. Setting the easeinspeed to 2 causes the ease in to go roughly twice as fast (animation strength increases faster), such that get animation gets to half strength after about 0.35 seconds. Assuming a constant frame rate, this is the exact formula for the ease in strength (assuming weight=1, blendmode=add). 1.0 - (1 - (1/framerate)*easeinstrength)^frame
easeoutspeed	decimal number	10	Multiplies the speed at which the animation eases out. See the easein field for an explanation of easing.
weightcapfactor	decimal number	0.0	This field allows the ease in and ease out to work in the Average/AddAverage blend modes. The field has no affect for the Add blend mode, where ease in and ease out work without setting this field. First, let's consider how the blending works without setting this field. Let's say animation A has weight 2 and animation B has weight 1, and they are both playing in the middle so ease in/out does not apply. Due to the weighted average, animation A will have 2/3 of its normal effect, and animation B will have 1/3 of its normal effect. Nothing wrong here. Next, let's consider what happens when animation A is eased in and animation B is playing at full strength with weight 1. Due to the ease in, animation A has weight 0.1. Now animation A gets 0.1/1.1 weight (low weight), and animation B gets 1/1.1 weight (almost full strength). Nothing wrong here either. Finally, let's consider what happens when only animation A is playing and it is getting eased in. Due to the easing, animation A only has strength 0.1. The total weight is 0.1. Animation A gets 0.1/0.1 = 1 (full strength)? That's not right; the ease in is supposed to reduce the strength of the animation. The weightcapfactor sets the minimum total weight. Let's say it is set to 1.0. Now let's revist the previous example. Animation A gets 0.1/max(1.0, 0.1) = 0.1/1.0 = 0.1. So with weightcapfactor=1.0, animation A gets properly eased in, even when it is the only animation playing. So for animations that use the Average/AddAverage modes, set weightcapfactor equal to the weight, for ease in/ease out to work properly. Note that the comment in the source code is wrong for this field as of 1.20.0-pre.4.
triggeredby			Specifies by what the animation is triggered.
oncontrols	array of strings		An array of activities that start the animation.
none
idle
move
sprintmode
sneakmode
fly
swim
jump
fall
climb
floorsitting
dead
break
place
glide
mounted
matchexact	boolean	false	If set to true, all OnControls elements need to be happening simultaneously to trigger the animation. If set to false, at least one OnControls element needs to be happening to trigger the animation.
defaultanim	boolean	false	Set to true if this animation should be played whenever no other animations are playing.
blendmode	string		Animation blend mode for all elements.
add			Add the animation without taking other animations into considerations.
average			Add the pose and average it together with all other running animations with blendmode Average or AddAverage.
addaverage			The comment in the source code says, "Add the animation without taking other animations into consideration, but add it's weight for averaging." However, it actually has done the same thing as Average since version 1.17.
elementblendmode	key: string, value: string		Allows you to specify a blend mode for each element individually. Any element not in this list defaults its blend mode to the value specified in blendmode.
suppressdefaultanimation	boolean	false	When this animation plays, stop the default animation, even if the entity class set alwaysRunIdle=true (as EntityPlayer does). When alwaysRunIdle=false, setting suppressdefaultanimation is unnecessary, because all non-default animations already stop the default animation.
holdeyeposaftereasein	decimal number	99	In first person immersive mode, the camera position is moved with the player entity's eye position as it moves from animations. However, once any of the playing animations have an ease value above this, then the camera is held in place until the ease value is reduced. This field is ignored for other camera modes, including first person non-immersive mode. The ease value ranges from 0 to 1, where 1 means the animation is at full strength. So setting holdeyeposaftereasein to a value of 1 or greater effectively disables this hold behavior. The camera is held forall animiations if any of the running animations have an ease value above their holdeyeposaftereasein. The point of this feature is to stop the cammera from slowly moving at the end of the animation. The ease feature uses an exponential decay formula, so it never quite reaches 1. holdeyeposaftereasein prevents the camera from slowly continuing to move forever. Note that as of 1.20.0-pre.4, the official documentation is wrong for this field.
clientside	boolean	false	Usually the client starts playing animations before the server, because the client learns about which keys are pressed before the server. Then later the server syncs its list of running animations with the client. The client stops any animations not in the received list. However, if clientside=true, then the client will not stop the animation based on the list received by the server.
withfpvariant	boolean	false	If true, then for player animations, use the animation specified in fpvariant instead of this animation. In first person mode, the player's entity can use different animations than the entities for other players or for the player in 3rd person. If withfpvariant=true, then the animation code is taken from this animation metadata object, with "-fp" appended. It inherits all of the other entries from this animation metadata object. If withfpvariant=false, it then tries to look up the animation metadata with the fpEnding suffix. The suffix is "-fp" in regular first person mode, and "-ifp" in immersive first person mode. If those are not found, then it uses the regular animation. So withfpvariant=true is used to save having to copy all of the animation metadata when the first person animation needs the same metadata but a different animation code, and immersive first person and first person use the same animation code.
animationsound	object	-	Play a sound while playing the animation
frame	integer	0	Which animation frame to start the sound on.
location	asset	-	Which sound to play.
randomizepitch	boolean	true	Randomly change pitch of the sound each time it is played.
range	decimal number	32	How many blocks away the sound can be heard from.
}
server: {
attributes	key: string, value: object	-	Custom Attributes associated with this entity only known by the server. They will not be send to the client.
	Extra attributes added to the entity for server use only. Those are final and cannot be modified. It's a good way to keep things organized and and modifiable. These can be used by behaviors or the entity class: attributes: { "attackPower": 10 },
behaviors	array of object		Server side entity behaviors.
spawnConditions	object	-	Specifies the circumstances of the entity spawn.
climate	object		If this is set, then it will override the climate settings in runtime and worldgen. When the entity has the same climate settings at runtime and worldgen, it is recommended to use this as a convenience to avoid copy pasting the climate settings into both sections.
mintemp	integer	-40	Minimum temperature at which the entity can spawn.
maxtemp	integer	40	Maximum temperature at which the entity can spawn.
minrain	decimal number	0	Minimum rain average at which the entity can spawn.
maxrain	decimal number	1	Maximum rain average at which the entity can spawn.
minforest	decimal number	0	Minimum forest density at which the entity can spawn.
maxforest	decimal number	1	Maximum forest density at which the entity can spawn.
minshrubs	decimal number	0	Minimum shrubs density at which the entity can spawn.
maxshrubs	decimal number	1	Maximum shrubs density at which the entity can spawn.
minforestorshrubs	decimal number	0	Minimum shrubs or forest density at which the entity can spawn.
minY	decimal number	0	Relative world height which the entity cannot spawn below. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the bottom of the world.
maxY	decimal number	2	Relative world height which the entity cannot spawn above. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the top of the world.
runtime	object		A set of spawn conditions for chunks that have already been generated.
group	string		The type of mob. Valid values: hostile neutral passive If this is set to hostile, the mob will be prevented from spawning in locations that prohibit hostile mobs.
chance	decimal number	1.0	How long it takes to make an attempt to spawn the entity: 1.0 -> 4 seconds, 0.1 -> 40 seconds.
maxquantity	integer	20	Stop spawning new entities of this type if there are this many or more entities of this type already in the single player world. With more than one player, the number is multipled by the spawnCapMul.
maxquantitybygroup	object	null	Stop spawning new entities of this type if there are this many or more entities that match this wildcard already in the single player world. With more than one player, the number is multipled by the spawnCapMul.
maxquantity	integer	0	Max number of entities that match the wildcard.
code	asset location string	""	Wildcard to match entities in the group.
mindistancetoplayer	integer	18	Minimum distance the entity can spawn away from the player.
minlightlevel	integer	0	The minimum light level for an object to spawn.
maxlightlevel	integer	32	The maximum light level for an object to spawn.
lightleveltype	string	"MaxLight"	The type of light counted towards minlightlevel and maxlightlevel for spawning purposes.
onlyblocklight			Will get you just the block light
onlysunlight			Will get you just the sun light unaffected by the day/night cycle
maxlight			Will get you max(onlysunlight, onlyblocklight)
maxtimeofdaylight			Will get you max(sunlight * sunbrightness, blocklight)
obsolete: groupsize	object		Alias for herdsize.
herdsize	NatFloat	{ avg: 1, var: 0 }	Determines the size of the group. By default the size of the group is always one.
companions	array of asset strings	-	The first entity in the spawned herd is always this entity. If the herd size (randomly chosen as described by herdsize) is greater than 1, and companions is non-empty, then the remaining entities are randomly chosen from companions. If companions is empty, then the remaining spawned entities are just copies of this entity.
insideblockcodes	array of string	[ "game:air" ]	The block codes in which the entity can spawn. Entities which can spawn underwater might use [ "game:water" ] instead.
requiresolidground	boolean	true	If the entity requires a solid block below it. For example birds and fishes do not require it.
tryonlysurface	boolean	false	If false the game will also try to spawn the entity below the surface (in a cave for example). For ordinary animals this should be true so they only spawn on the surface.
climatevaluemode	EnumGetClimateMode string	worldgenvalues	Whether the rain and temperature values are referring to the worldgen values (i.e. yearly averages) or the current values at the moment of spawning. Valid values: WorldGenValues The values generate during world generation, these are loosely considered as yearly averages NowValues The values at the current calendar time ForSuppliedDateValues The values at the supplied calendar time, supplied as additional arg ForSuppliedDate_TemperatureOnly The values at the supplied calendar time, ignoring rainfall etc. ForSuppliedDate_TemperatureRainfallOnly The values at the supplied calendar time, ignoring forest cover etc.
mintemp	integer	-40	Minimum temperature at which the entity can spawn.
maxtemp	integer	40	Maximum temperature at which the entity can spawn.
minrain	decimal number	0	Minimum rain average at which the entity can spawn.
maxrain	decimal number	1	Maximum rain average at which the entity can spawn.
minforest	decimal number	0	Minimum forest density at which the entity can spawn.
maxforest	decimal number	1	Maximum forest density at which the entity can spawn.
minshrubs	decimal number	0	Minimum shrubs density at which the entity can spawn.
maxshrubs	decimal number	1	Maximum shrubs density at which the entity can spawn.
minforestorshrubs	decimal number	0	Minimum shrubs or forest density at which the entity can spawn.
minY	decimal number	0	Relative world height which the entity cannot spawn below. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the bottom of the world.
maxY	decimal number	2	Relative world height which the entity cannot spawn above. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the top of the world.
worldgen	object		A set of spawn conditions for when chunks are generated.
group	string		The type of mob. Valid values: hostile neutral passive If this is set to hostile, the mob will be prevented from spawning in locations that prohibit hostile mobs.
triesperchunk	NatFloat	zero	How many tries per chunk the entity has to spawn.
minlightlevel	integer	0	The minimum light level for an object to spawn.
maxlightlevel	integer	32	The maximum light level for an object to spawn.
lightleveltype	string	"MaxLight"	The type of light counted towards minlightlevel and maxlightlevel for spawning purposes.
onlyblocklight			Will get you just the block light
onlysunlight			Will get you just the sun light unaffected by the day/night cycle
maxlight			Will get you max(onlysunlight, onlyblocklight)
maxtimeofdaylight			Will get you max(sunlight * sunbrightness, blocklight)
obsolete: groupsize	object		Alias for herdsize.
herdsize	NatFloat	{ avg: 1, var: 0 }	Determines the size of the group. By default the size of the group is always one.
companions	array of asset strings	-	The first entity in the spawned herd is always this entity. If the herd size (randomly chosen as described by herdsize) is greater than 1, and companions is non-empty, then the remaining entities are randomly chosen from companions. If companions is empty, then the remaining spawned entities are just copies of this entity.
insideblockcodes	array of string	[ "game:air" ]	The block codes in which the entity can spawn. Entities which can spawn underwater might use [ "game:water" ] instead.
requiresolidground	boolean	true	If the entity requires a solid block below it. For example birds and fishes do not require it.
tryonlysurface	boolean	false	If false the game will also try to spawn the entity below the surface (in a cave for example). For ordinary animals this should be true so they only spawn on the surface.
climatevaluemode	EnumGetClimateMode string	worldgenvalues	Whether the rain and temperature values are referring to the worldgen values (i.e. yearly averages) or the current values at the moment of spawning. Valid values: WorldGenValues The values generate during world generation, these are loosely considered as yearly averages NowValues The values at the current calendar time ForSuppliedDateValues The values at the supplied calendar time, supplied as additional arg ForSuppliedDate_TemperatureOnly The values at the supplied calendar time, ignoring rainfall etc. ForSuppliedDate_TemperatureRainfallOnly The values at the supplied calendar time, ignoring forest cover etc.
mintemp	integer	-40	Minimum temperature at which the entity can spawn.
maxtemp	integer	40	Maximum temperature at which the entity can spawn.
minrain	decimal number	0	Minimum rain average at which the entity can spawn.
maxrain	decimal number	1	Maximum rain average at which the entity can spawn.
minforest	decimal number	0	Minimum forest density at which the entity can spawn.
maxforest	decimal number	1	Maximum forest density at which the entity can spawn.
minshrubs	decimal number	0	Minimum shrubs density at which the entity can spawn.
maxshrubs	decimal number	1	Maximum shrubs density at which the entity can spawn.
minforestorshrubs	decimal number	0	Minimum shrubs or forest density at which the entity can spawn.
minY	decimal number	0	Relative world height which the entity cannot spawn below. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the bottom of the world.
maxY	decimal number	2	Relative world height which the entity cannot spawn above. 0...1 is world bottom to sea level, 1...2 is sea level to world top. So the default value means that the entity can spawn all the way at the top of the world.
}

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.

.

Little Figure

The idea is create a little passive figure, made out of wood. The modid of our mod will be figure.

EntityType

Common

So first of all we have to create the entity type file assets/figure/entities/land/littlefigure.json. Now we go through all the properties:

code: The unique identifier for your entity. A prefix of your mod id will be added automatically. Our case its figure:littlefigure.

class: The class of the entity, it can be used to program special features for it. We don't need it at the moment, so we set it to EntityAgent.

hitboxSize: The size of the hitbox.

  "hitboxSize": {
    "x": 0.4,
    "y": 0.5
  },

deadHitboxSize: The size of the hitbox when the entity has died.

  "deadHitboxSize": {
    "x": 0.4,
    "y": 0.5
  },

eyeHeight: The height of the eyes, which is 0.4 for the little figure.

drops: A list of items to be dropped (can also include chances). We leave it empty for now: [].

sounds: Set the sounds for the entity

    "hurt": "creature/figure-hurt",
    "death": "creature/figure-death",
    "idle": "creature/figure-idle"

Client

The client type has different properties for client and server. This will cover the client side (rendering, shape, texture)

(please note that // comments are actually not a valid json syntax, so if you want to use this json code in your projects, you'd have to remove these first)

  "client": {
    "renderer": "Shape", // How the entity will be rendered, "Shape" is the right one in almost all cases.
    "shape": { "base": "entity/land/littlefigure" }, // a path to our shape
    "texture": { "base": "game:block/wood/planks/birch1" }, // the figure should have the texture of birch wood. Therefore the prefix "game" is needed
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics", // Adds physics to the entity
        "stepHeight": 0.2
      },
      {
        "code": "floatupwhenstuck", // Fixes corpse get stuck in ground
        "onlyWhenDead": true
      },
      { "code": "interpolateposition" } // Smooths out movement of entity
    ],
    "animations": [ // Animations which have to be implemented by the shape as well
      {
        "code": "hurt",
        "animation": "hurt",
        "animationSpeed": 2.2,
        "weight": 10,
        "blendMode": "AddAverage"
      },
      {
        "code": "die",
        "animation": "die",
        "animationSpeed": 1.25,
        "weight": 10,
        "blendMode": "AddAverage"
      }
    ]
  },

Server

The server side handles the "brain" of the entity.

  "server": {
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics", // Adds physic interaction
        "stepHeight": 0.2
      },
      {
        "code": "health", // Adds a health bar to the entity
        "currenthealth": 4,
        "maxhealth": 4
      },
      {
        "code": "deaddecay", // Makes the dead entity stay for one hour
        "hoursToDecay": 1
      },
      {
        "code": "floatupwhenstuck", // Fixes corpse get stuck in ground
        "onlyWhenDead": true
      },
      {
        "code": "despawn", // Makes the entity despawn if there is no player within 48 blocks
        "minPlayerDistance": 48,
        "minSeconds": 5
      },
      {
        "code": "emotionstates", // Adds different emotion states
        "states": [
          {
            "code": "fleeondamage", // After the entity is hit it will try to flee for 10 seconds
            "duration": 10,
            "chance": 0.2,
            "slot": 0,
            "priority": 1,
            "accumType": "max"
          }
        ]
      },
      {
        "code": "taskai", // Handles what the entity does, a task will be processed one at a time
        "aitasks": [
          {
            "code": "idle", // the figure will stand still and think
            "priority": 1.2,
            "priorityForCancel": 1.35,
            "minduration": 4000,
            "maxduration": 6000,
            "chance": 0.001,
            "initialMinCoolDown": 2000,
            "initialMaxCoolDown": 150000,
            "mincooldown": 300000,
            "maxcooldown": 10000000,
            "animation": "think",
            "animationSpeed": 1.25
          },
          {
            "code": "wander", // The entity will walk around
            "priority": 1.0,
            "movespeed": 0.008,
            "animationSpeed": 1.6,
            "animation": "run",
            "preferredLightLevel": 15
          },
          {
            "code": "lookaround", // The entity will look around
            "priority": 0.5
          }
        ]
      }
    ]
  },

Result

If we put everything together it should look like this:

{
  "code": "littlefigure",
  "class": "EntityAgent",
  "hitboxSize": {
    "x": 0.4,
    "y": 0.5
  },
  "deadHitboxSize": {
    "x": 0.4,
    "y": 0.5
  },
  "eyeHeight": 0.4,
  "drops": [],
  "client": {
    "renderer": "Shape",
    "shape": { "base": "entity/land/littlefigure" },
    "texture": { "base": "game:block/wood/planks/birch1" },
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics",
        "stepHeight": 0.2
      },
      {
        "code": "floatupwhenstuck",
        "onlyWhenDead": true
      },
      { "code": "interpolateposition" }
    ],
    "animations": [
      {
        "code": "hurt",
        "animation": "hurt",
        "animationSpeed": 2.2,
        "weight": 10,
        "blendMode": "AddAverage"
      },
      {
        "code": "die",
        "animation": "die",
        "animationSpeed": 1.25,
        "weight": 10,
        "blendMode": "AddAverage"
      }
    ]
  },
  "server": {
    "behaviors": [
      { "code": "repulseagents" },
      {
        "code": "controlledphysics",
        "stepHeight": 0.2
      },
      {
        "code": "health",
        "currenthealth": 4,
        "maxhealth": 4
      },
      {
        "code": "deaddecay",
        "hoursToDecay": 1
      },
      {
        "code": "floatupwhenstuck",
        "onlyWhenDead": true
      },
      {
        "code": "despawn",
        "minPlayerDistance": 48,
        "minSeconds": 5
      },
      {
        "code": "emotionstates",
        "states": [
          {
            "code": "fleeondamage",
            "duration": 10,
            "chance": 0.2,
            "slot": 0,
            "priority": 1,
            "accumType": "max"
          }
        ]
      },
      {
        "code": "taskai",
        "aitasks": [
          {
            "code": "idle",
            "priority": 1.2,
            "priorityForCancel": 1.35,
            "minduration": 4000,
            "maxduration": 6000,
            "chance": 0.001,
            "initialMinCoolDown": 2000,
            "initialMaxCoolDown": 150000,
            "mincooldown": 300000,
            "maxcooldown": 10000000,
            "animation": "think",
            "animationSpeed": 1.25
          },
          {
            "code": "wander",
            "priority": 1.0,
            "movespeed": 0.008,
            "animationSpeed": 1.6,
            "animation": "run",
            "preferredLightLevel": 15
          },
          {
            "code": "lookaround",
            "priority": 0.5
          }
        ]
      }
    ]
  },
  "sounds": {
    "hurt": "creature/figure-hurt",
    "death": "creature/figure-death",
    "idle": "creature/figure-idle"
  }
}

Shape

If you want to know how to create the shape for the entity I suggest you checkout VS Model Creator.

Item

In order to spawn the entity we can create an item to do so:

{
  "code": "creature",
  "class": "ItemCreature",
  "maxstacksize": 64,
  "variantgroups": [
    {
      "code": "type",
      "states": [ "littlefigure" ]
    }
  ],
  "shape": {
    "base": "figure:entity/land/littlefigure"
  },
  "texture": { "base": "game:block/wood/planks/birch1" },
  "creativeinventory": {
    "general": [ "*" ],
    "items": [ "*" ],
    "creatures": [ "*" ]
  },
  "materialDensity": 600,
  "guiTransform": {
    "rotation": {
      "x": 0,
      "y": -90,
      "z": -180
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  },
  "fpHandTransform": {
    "rotation": {
      "x": 0,
      "y": -90,
      "z": 0
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  },
  "groundTransform": {
    "translation": {
      "x": 0,
      "y": 0.15,
      "z": 0
    },
    "rotation": {
      "x": 0,
      "y": -90,
      "z": 0
    },
    "origin": {
      "x": 0.5,
      "y": 0.15,
      "z": 0.5
    },
    "scale": 6
  }
}

Testing/ Distribution

Download Figure v1.0.0 for VintageStory 1.8

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.