Entity Json Properties

From Vintage Story Wiki
Jump to: navigation, search

Overview

A complete list of all available properties

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.

The variantgroups property allows you to define multiple variants of this entity. All of them will have their unique pattern, which will be added to the entity code.

An easy example would be a sheep, which can either be small or tall:

	variantgroups: [
		{ code:"size", states: ["small", "tall"] },
	],

Meaning there will be two blocks sheep-small and sheep-tall.


It's also possible to define multiple groups.

	variantgroups: [
		{ code:"size", states: ["small", "tall"] },
		{ code:"color", states: ["white", "black"] },
	],

As a result you will have 2x2 groups, which will be added one after each other: sheep-small-white, sheep-tall-white, sheep-small-black and sheep-tall-black.


Additionally it is possible to refer to external lists that are found in the worldproperties folder, such as block/rock, which contains all states of all rock types. This used for gravel, sand and rock. It's a good way to keep everything organized:

	variantgroups: [
		{ loadFromProperties: "block/rock" },
	],

Here is a full list of all groups and their variants (you can also find them in the assets/worldproperties folder):

Name States
block/grass -
block/mushroom flyagaric, bolete, fieldmushroom
block/herb basil, chamomile, cilantro, lavender, marjoram, mint, saffron, sage, thyme
block/flower catmint, forgetmenot, edelweiss, heather, horsetail, orangemallow, wilddaisy, westerngorse, cowparsley, californiapoppy
block/metal bismuth, bismuthbronze, blackbronze, brass, chromium, copper, gold, iron, lead, platinum, rhodium, silver, stainlesssteel, steel, tin, tinbronze, titanium, uranium, zinc
block/ore lignite, bituminouscoal, nativecopper, limonite, quartz_nativegold, galena, cassiterite, chromite, platinum, ilmenite, sphalerite, rocksalt_sylvite, quartz_nativesilver, lapislazuli, diamond, emerald, bismuthinite, quartz, rocksalt, sulfur, magnetite
block/tallgrass veryshort, short, mediumshort, medium, tall, verytall, eaten
block/rock andesite, chalk, claystone, granite, sandstone, shale
block/woodwithaged birch, oak, maple, pine, acacia, kapok, aged
block/wood birch, oak, maple, pine, acacia, kapok
block/painting acitasluna, dandelionnight, distantpath, forestpath, night, papiliorumanzovia, stillmomentsbeforesunrise, thedreamprojection, troidesaeacus, winterflowers
abstract/rockgroup -
abstract/alloy -
abstract/fertility verylow, low, medium, high
abstract/grasscoverage none, verysparse, sparse, normal
abstract/horizontalorientation north, east, south, west
abstract/verticalorientation up, down
abstract/coating n, e, s, w, u, d, ud, ns, ew, nd, ed, sd, wd, su, wu, nu, eu, es, sw, nw, ne, nwd, ned, esd, swd, nwu, neu, esu, swu, nsd, ewd, sud, wud, nud, eud, nsu, ewu, nes, esw, nsw, new, newd, nesd, eswd, nswd, eswu, nswu, newu, nesu, nesw, ewud, nsud, neud, esud, swud, nwud, neswd, neswu, newud, nesud, eswud, nswud, neswud

Futhermore there are two ways of combining groups together. So far we covered the default combination mode, which is multiplicative (the total count of variants is the product of all states).

Imagine you want to implement a living tree, were either flowers, mushrooms or saplings or on it. You can use the additive combination mode for that:

	variantgroups: [
		{ code: "type", loadFromProperties: "block/wood" },
		{ code: "flower", loadFromProperties: "block/flower", combine: "additive" },
		{ code: "mushroom", loadFromProperties: "block/mushroom", combine: "additive" },
		{ code: "sapling", loadFromProperties: "block/wood", combine: "additive" },
	],

The living trees exists for every wood type (birch, oak, maple, pine, acacia, kapok) and can either have a flower, mushroom or a sapling suffix: livingtree-{wood type}-{flower}, livingtree-{wood type}-{all flowers}, livingtree-{wood type}-{all mushrooms} and livingtree-{wood type}-{all saplings}.

(any) byType
key: string; value: object - You can create properties for certain variants of the block.

In order to define properties for specific variants you can add byType to the property name. This allows you to define it depending on the type and always follows the same syntax:

	(property)ByType: {
		"selector": property,
		"selector2": property2,
		...
	}

If the selector matches the name of the variant the given property will be used. Keep in mind that only the first matching one will be used (everything below will be ignored).

An entity for example has two variants (big, small):

	falldamagebyType: {
		"*-big": true,
		"*-small": false
	},

Since Vintagestory v1.8 it is also possible to use the variantgroup as a placeholder:

	variantgroups: [
		{ code: "type", states: ["normal", "bamboo"] },
	],
	texture: { base: "entity/fish/{type}" }
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 and air
HitBoxSize
object x: 0.125, y: 0.125 The size of the hitbox, either to hit the entity or to interact with it.
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.
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.
FallDamage
boolean true Whether the entity will take fall damage.
ClimbTouchDistance
decimal number 0.5 Distance at which the entity can climb on something.
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
	},
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.
Texture
object The texture of the entity. It will overwrite all textures of 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: object 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
object - 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.
Behaviors
array of object A behavior adds custom abilities to the entity.
Name Explanation Properties Side
collectitems The entity collections items laying around on the ground. Used by player. Server
health Applies custom health to the entity. Means the entity can be hurt as well. currenthealth = 20, maxhealth = 20, basemaxhealth = 20 Server
hunger Adds saturation and hunger, the entity needs to eat in order to stay alive. currentsaturation = 1200, maxsaturation = 1200, saturationlossdelay = 60 * 24, currentfruitLevel = 0, currentvegetableLevel = 0, currentgrainLevel = 0, currentproteinLevel = 0, currentdairyLevel = 0 Server
breathe The entity will need to breathe and therefore suffocate in other blocks (for example sand). Server
playerphysics Makes an entity controllable by a player. stepHeight = 0.6 Universal
controlledphysics Can be controlled by a player. stepHeight = 0.6 Universal
taskai Allows you to specify tasks.
interpolateposition Interpolates entity position and rotate. Smooths out the animations. It's a visual effect, therefore not available on server side. Client
despawn The entity will despawn under given circumstances. minPlayerDistance, belowLightLevel, minSeconds = 30 Server
grow The entity will grow and eventually turn into one of its adults. hoursToGrow = 96, adultEntityCodes = [] Server
multiply A pack of wolves for example grows in size over time (new babies are born). pregnancyDays = 3.0, spawnEntityCode, requiresNearbyEntityCode, requiresNearbyEntityRange = 5, multiplyCooldownDaysMin = 6, multiplyCooldownDaysMax = 12, portionsEatenForMultiply = 3, spawnQuantityMin = 1, spawnQuantityMax = 2, requiresFood = true Server
aimingaccuracy Adds aiming inaccuracy when sprinting, jumping, etc. Universal
emotionstates Adds emotion states with a given chance. As an example, it can be used to make an animal "hungry" (aggressive) and "saturated" (passive). Server
repulseagents Pushes other entities back. Universal
tiredness The entity will get tired over time and needs recover by sleeping in a bed. currenttiredness = 0 Universal
nametag Adds a name tag to the entity which will be displayed above the entity. selectFromRandomName Universal
placeblock The entity will place one of the given block codes from time to time. minHourDelay = 8 * 24, maxHourDelay = 15*24, blockCodes = [] Server
passivephysics Adds physics to the entity. waterDragFactor = 1, airDragFallingFactor = 1, groundDragFactor = 1, gravityFactor = 1 Universal
Animations
array of object WIP
Code
string The identifier of the animation.
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 should be affected by the walk speed.
EaseInSpeed
decimal number 10
EaseOutSpeed
decimal number 10
TriggeredBy
Specifies by what the animation is triggered.
OnControls
array of object An array of activities.
None
Idle
Move
SprintMode
SneakMode
Fly
Swim
Jump
Fall
Climb
FloorSitting
Dead
Break
Place
MatchExact
boolean false
DefaultAnim
boolean false
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
Add the animation without taking other animations into consideration, but add it's weight for averaging.
ElementBlendMode
key: string, value: string Allows you to specify a blend mode for each element individually.
}
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 A behavior adds custom abilities to the entity.
Name Explanation Properties Side
collectitems The entity collections items laying around on the ground. Used by player. Server
health Applies custom health to the entity. Means the entity can be hurt as well. currenthealth = 20, maxhealth = 20, basemaxhealth = 20 Server
hunger Adds saturation and hunger, the entity needs to eat in order to stay alive. currentsaturation = 1200, maxsaturation = 1200, saturationlossdelay = 60 * 24, currentfruitLevel = 0, currentvegetableLevel = 0, currentgrainLevel = 0, currentproteinLevel = 0, currentdairyLevel = 0 Server
breathe The entity will need to breathe and therefore suffocate in other blocks (for example sand). Server
playerphysics Makes an entity controllable by a player. stepHeight = 0.6 Universal
controlledphysics Can be controlled by a player. stepHeight = 0.6 Universal
taskai Allows you to specify tasks.
interpolateposition Interpolates entity position and rotate. Smooths out the animations. It's a visual effect, therefore not available on server side. Client
despawn The entity will despawn under given circumstances. minPlayerDistance, belowLightLevel, minSeconds = 30 Server
grow The entity will grow and eventually turn into one of its adults. hoursToGrow = 96, adultEntityCodes = [] Server
multiply A pack of wolves for example grows in size over time (new babies are born). pregnancyDays = 3.0, spawnEntityCode, requiresNearbyEntityCode, requiresNearbyEntityRange = 5, multiplyCooldownDaysMin = 6, multiplyCooldownDaysMax = 12, portionsEatenForMultiply = 3, spawnQuantityMin = 1, spawnQuantityMax = 2, requiresFood = true Server
aimingaccuracy Adds aiming inaccuracy when sprinting, jumping, etc. Universal
emotionstates Adds emotion states with a given chance. As an example, it can be used to make an animal "hungry" (aggressive) and "saturated" (passive). Server
repulseagents Pushes other entities back. Universal
tiredness The entity will get tired over time and needs recover by sleeping in a bed. currenttiredness = 0 Universal
nametag Adds a name tag to the entity which will be displayed above the entity. selectFromRandomName Universal
placeblock The entity will place one of the given block codes from time to time. minHourDelay = 8 * 24, maxHourDelay = 15*24, blockCodes = [] Server
passivephysics Adds physics to the entity. waterDragFactor = 1, airDragFallingFactor = 1, groundDragFactor = 1, gravityFactor = 1 Universal
SpawnConditions
object - Specifies the circumstances of the entity spawn.
Runtime
object
Group
string
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 Maximum number of entities inside the chunk, if this is exceeded the entity will not spawn there.
MinDistanceToPlayer
integer 18 Minimum distance the entity can spawn away from the player.
MinLightLevel
integer 0
MaxLightLevel
integer 32
LightLevelType
string "MaxLight"
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)
GroupSize
object { avg: 1, var: 0 } Determines the size of the group. By default the size of the group is always one. Find out more about the random generator.
Companions
array of string - Codes of all possible companions.
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.
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.
Worldgen
object
Group
string
TriesPerChunk
object zero How many tries per chunk the entity has to spawn. Find out more about the random generator.
MinLightLevel
integer 0
MaxLightLevel
integer 32
LightLevelType
string "MaxLight"
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)
GroupSize
object { avg: 1, var: 0 } Determines the size of the group. By default the size of the group is always one. Find out more about the random generator.
Companions
array of string - Codes of all possible companions.
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.
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.
}



Vintage Story: Modding
Basics Mod Types | Asset System | Textures | Items | Recipes | Blocks | Model Creator | Release
Advanced Setup(Windows,Linux) | Items | Blocks | Item-Block interractions | Block Behavior | Block Entity | Particles | World Access
Worldgen Terrain | Ores | Trees | Worldgen API
Rendering Shaders and Renderers
Property Overview Item | Block