Modding:Block Json Properties: Difference between revisions

From Vintage Story Wiki
No edit summary
No edit summary
Line 4: Line 4:


<table id="treeviewtable" class="table table-bordered tt-table" style='table-layout: fixed'>
<table id="treeviewtable" class="table table-bordered tt-table" style='table-layout: fixed'>
   <tr style='background-color: gray;'>
   <tr>
     <th width='300' align='left'>Property</th>
     <th width='300' align='left'>Property</th>
     <th width='200' align='left'>Type</th>
     <th width='200' align='left'>Type</th>

Revision as of 10:16, 6 February 2019

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

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 stone turns into game:stone.

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 block will be loaded or not. Can be used to temporarily remove the block.
VariantGroups
array of object - Allows you define multiple variants of the same block.

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

An easy example would be a bowl, which can either be raw or burned:

	variantgroups: [
		{ code:"type", states: ["raw", "burned"] },
	],

Meaning there will be two blocks bowl-raw and bowl-burned.


It's also possible to define multiple groups.

	variantgroups: [
		{ code:"state", states: ["closed", "opened"] },
		{ code:"contents", states: ["empty", "cabbage"] },
	],

As a result you will have 2x2 groups, which will be added one after each other: barrel-closed-empty, barrel-closed-cabbage, barrel-opened-empty and barrel-opened-cabbage.


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): The world properties are stored in the assets/survival/worldproperties folder. They are used to help fill in the variantgroups field. Instead of directly specifying every state in the variant group, the states can be loaded from a world property through the loadFromProperties key. The states from multiple world properties can be added with the loadFromPropertiesCombine key, which takes an array of strings. The states key can still be optionally added to the variant group to specify additional states.

For example, the following creates a variant group named orientation. It contains 5 states. north, east, south, and west are loaded from the abstract/horizontalorientation world property. up is added to the list of states.

	variantgroups: [
		{ code: "orientation", states: ["up"], loadFromProperties: "abstract/horizontalorientation" }
	],

Unwanted variant states can be filtered out with the skipVariants property. Or all states that do not match an expression can be filtered out with the allowedVariants property.

Name States
abstract/alloy -
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
abstract/fertility verylow, low, medium, compost, high
abstract/grasscoverage none, verysparse, sparse, normal
abstract/horizontalorientation north, east, south, west
abstract/rockgroup -
abstract/verticalorientation up, down
block/flower catmint, cornflower, forgetmenot, edelweiss, heather, horsetail, orangemallow, wilddaisy, westerngorse, cowparsley, goldenpoppy, lilyofthevalley, woad, redtopgrass
block/fruit blueberry, cranberry, redcurrant, whitecurrant, blackcurrant, saguaro, pineapple, redapple, pinkapple, yellowapple, cherry, peach, pear, orange, mango, breadfruit, lychee, pomegranate
block/grass -
block/herb basil, chamomile, cilantro, lavender, marjoram, mint, saffron, sage, thyme
block/metal bismuth, bismuthbronze, blackbronze, brass, chromium, copper, cupronickel, electrum, gold, iron, meteoriciron, lead, molybdochalkos, platinum, nickel, silver, stainlesssteel, steel, tin, tinbronze, titanium, uranium, zinc
block/mushroom flyagaric, fieldmushroom, almondmushroom, bitterbolete, blacktrumpet, chanterelle, commonmorel, deathcap, devilstooth, devilbolete, earthball, elfinsaddle, golddropmilkcap, greencrackedrussula, indigomilkcap, jackolantern, kingbolete, lobster, orangeoakbolete, paddystraw, puffball, redwinecap, saffronmilkcap, violetwebcap, witchhat, beardedtooth, chickenofthewoods, dryadsaddle, pinkoyster, tinderhoof, whiteoyster, reishi, funeralbell, deerear, livermushroom, pinkbonnet, shiitake
block/ore-gem-cut diamond, emerald, peridot
block/ore-gem-rough diamond,emerald,olivine_peridot
block/ore-graded nativecopper,limonite,quartz_nativegold,galena,cassiterite,chromite,ilmenite,sphalerite,quartz_nativesilver,galena_nativesilver,bismuthinite,magnetite,hematite,malachite,pentlandite,uranium,wolframite,rhodochrosite
block/ore-nugget nativecopper,limonite,nativegold,galena,cassiterite,chromite,ilmenite,sphalerite,nativesilver,bismuthinite,magnetite,hematite,malachite,pentlandite,uranium,wolframite,rhodochrosite
block/ore-ungraded alum,lapislazuli,corundum,anthracite,borax,cinnabar,lignite,bituminouscoal,sylvite,quartz,olivine,sulfur,fluorite,graphite,kernite,phosphorite
block/painting howl,elk,underwater,prey,forestdawn,fishandtherain,bogfort,castleruin,cow,hunterintheforest,seraph,sleepingwolf,sunkenruin,traveler,oldvillage,lastday,sodhouse
block/rock andesite,chalk,chert,conglomerate,limestone,claystone,granite,sandstone,shale,basalt,peridotite,phyllite,slate,bauxite
block/rockwithdeposit andesite,chalk,chert,conglomerate,limestone,claystone,granite,sandstone,shale,basalt,peridotite,phyllite,slate,obsidian,kimberlite,scoria,tuff,bauxite,halite,suevite,whitemarble,redmarble,greenmarble
block/tallgrass veryshort,short,mediumshort,medium,tall,verytall,eaten
block/toolmetal bismuth,bismuthbronze,blackbronze,brass,copper,gold,iron,meteoriciron,lead,molybdochalkos,silver,steel,tinbronze
block/wood birch,oak,maple,pine,acacia,kapok,baldcypress,larch,redwood,ebony,walnut,purpleheart
Icon Sign.png

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.



Furthermore 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).

Let's take a look at a different example (flowerpot), which uses the additive combination mode:

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

The variants are flowerpot-raw, flowerpot-empty, flowerpot-{all flowers}, flowerpot-{all mushrooms} and flowerpot-{all saplings}.

Additive mode could also be called separate, since it defines a variant separate from all the other groups:

	variantgroups: [
		{ code: "something", states: ["same", "different"] },
		{ code: "type", states: ["raw", "baked"] },
		{ code: "empty", states: ["red", "green"], "combine": "additive" },
	],

In this case, the result would be same-raw, same-baked, different-raw, different-baked, red and green

(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).

A slab for example has two variants (up, down), which have different collision boxes:

	collisionboxByType: {
		"*-down": { x1: 0, y1: 0, z1: 0,   x2: 1, y2: 0.5, z2: 1 },
		"*-up": { x1: 0, y1: 0.5, z1: 0,   x2: 1, y2: 1, z2: 1 }
	},

The char * stands for anything. In this case it ignores the code of the block.

Furthermore this opens up even more possbilities for more advanced selectors like this one for doors: *-north-*-opened-left. This will ignore the second variantgroup. Additionally ByType can also be used for child properties:

	collisionboxnbox: { 
		x1: 0, y1: 0, z1: 0.875, x2: 1, y2: 1, z2: 1,
		rotateYByType: {
			"*-north-*-opened-left": 90,
			"*-north-*-closed-left": 0,
			"*-west-*-opened-left": 180,
			"*-west-*-closed-left": 90,

			"*-east-*-opened-left": 0,
			"*-east-*-closed-left": 270,
			"*-south-*-opened-left": 270,
			"*-south-*-closed-left": 180,

			"*-north-*-opened-right": 270,
			"*-north-*-closed-right": 0,
			"*-west-*-opened-right": 0,
			"*-west-*-closed-right": 90,

			"*-east-*-opened-right": 180,
			"*-east-*-closed-right": 270,
			"*-south-*-opened-right": 90,
			"*-south-*-closed-right": 180
		}
	},

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

	variantgroups: [
		{ code: "type", states: ["normal", "bamboo"] },
	],
	textures: {
		horizontals: { base: "block/hay/{type}-side" },
		verticals: { base: "block/hay/{type}-top" },
	},
Specific
Class
string "block" The block class can add special functionalities for the block.

It can be used to open guis or adding other extra functionality to the block. A complete tutorial of how to add your own class to the game can be found here.

EntityClass
string - The block entity class is able to tick and to store extra data.

A chest for example uses the BlockEntity to store the inventory. A tutorial of creating your own entityclass can be found here.

Behaviors
array of object - A behavior adds custom abilities such as falling block.

Here is an overview of all exisiting behaviors, if you want to create your own custom behavior you can read Adding Block Behavior.

Adding behaviors to your block

Block behaviors are an array of objects with properties attached to your block. They are added through the behaviors field at the top level (same level as the code field) of a block json file. Below is an example of two behaviors, one with properties and one without properties.

{
  ...
  code: "exampleblock",
  ...
  behaviors: [{name: "behavior1", properties: {myProperty1: "myValue1", myProperty2: "myValue2"}},{name: "behavior2"}],
  ...
}

All Block Behaviors

Here is a table containing all properties of the base game as of 1.18.14.

Behavior Name Properties Used by Blocks
BlockEntityInteract - door
BreakIfFloating - termitemound, crackedrock, meteorite, ore, ore, ore, rock, rottenlog
BreakSnowFirst - tallgrass, stonepath
CanAttach
  • sides
drystonefence, woodenfence, roughhewnfence
CanIgnite - torch
CollectFrom - henbox
Container - storagevessel, stove, hopper, quern, crate, labeledchest, trunk, chest, firepit, stationarybasket
Decor
  • sides
  • sidedVariants
  • nwOrientable
  • drawIfCulled
  • alternateZOffset
  • notFullFace
  • removable
  • thickness
linen, mediumcarpet, rushmat, smallcarpet, wallpaper, wool, hotspringbacteriasmooth, hotspringbacteria, attachingplant, overlay, overlay, oxidation, transition, fallenleaves, caveart
Door - door
DropNotSnowCovered - fern, flower
ExchangeOnInteract
  • exchangeStates (string array of block states)
  • sounds (path from sounds folder)
  • actionLangCode (language key from the lang file)
trapdoor
FiniteSpreadingLiquid
  • liquidCollisionSound (path from sounds folder)
  • sourceReplacementCode (block code)
  • flowingReplacementCode (block code)
  • collidesWith (other liquid)
  • spreadDelay (int, default: 0)
boilingwater, water, lava, saltwater
Harvestable
  • harvestTime (float, seconds, default: 0)
  • harvestedStack (BlockDropItemStack)
  • harvestingSound (path from sounds folder)
  • harvestedBlockCode (block code)
bigberrybush, saguarocactus, smallberrybush, log-resin
HeatSource
  • heatStrength (float)
boilingwater, lava, forge, firepit, pitkiln, coalpile, ember, fire
HorizontalAttachable
  • handleDrops (bool, default: true)
  • dropBlockFace (Compass Direction, default: "north")
  • dropBlock (block name)
  • attachmentAreas (side -> RotatableCube)
  • attachmentArea (cuboid)
tapestry, torchholder, mushroom, canvas, moldrack, painting, shelf, toolrack
HorizontalOrientable
  • dropBlockFace (Compass Direction, default: "North")
  • drop (block name)
agedwallpaperplanks, altar, bellows, bloomerybase, brake, cage, churn, clayoven, clutch, cokeovendoor, condenser, crank, creativerotor, helvehammerbase, jonas, labeledchest, metalpartpile, palisadestakes, palisadewall, pulverizerframe, resonator, skep, slantedroofing, slantedroofingcornerinner, slantedroofingcornerouter, statictranslocator, stationarybasket, stonecoffinsection, stove, trunk, verticalboiler, wagonwheels, windmillrotor, workbench
HorizontalUpDownOrientable - -
Ignitable - charcoalpit, clayoven, firepit
JonasBoilerDoor - jonas
JonasGasifier - jonas
JonasHydraulicPump - jonas
Ladder
  • dropBlockFace (face direction, Default: north)
  • isFlexible (bool, default: false)
ladder
Lockable - archimedesscrew, chest, chute, cokeovendoor, crate, door, hopper, irondoor, labeledchest, roughhewnfencegate, stationarybasket, storagevessel, trapdoor, trunk, woodenfencegate
MilkingContainer - woodbucket
Multiblock
  • sizex
  • sizey
  • sizez
  • type
  • cposition
jonas, riftward, verticalboiler, banner, trunk, painting
MyceliumHost - creativegrass, forestfloor, log, soil
NoParticles - claybrickchimney
NWOrientable - bookshelves (legacy), claybrickchimney, fruitpress, fruitpresstop, mannequin, slantedroofingridge, transmission, trough, woodenpath, woodentoggle
OmniAttachable
  • facingCode (string, default: orientation)
  • attachmentAreas (side -> RotatableCube)
crystal, lantern
OmniRotatable
  • rotateH (bool, default: false)
  • rotateV (bool, default: false)
  • rotateV4 (bool, default: false)
  • rotateSides (bool, default: false)
  • facing (string, "block" or "player", default: "player")
  • dropChance(float, default: 1)
brickslabs, clayshinglelabs, cobblestoneslab, glassslab, mudbrickslab, plankslab, polishedrockslab, quartzslab, stonebrickslab, trapdoor
Pillar
  • invertedPlacement (bool, default: false)
carvedlog, debarkedlog, hay, log, lognarrow, planks, plaster, quartzpillar, stackedbamboo, woodenaxle
Pumpkin
  • vineGrowthStage(int)
  • vineGrowthQuantity(NatFloat)
crop
PushEventOnBlockBroken
  • eventName (string)
bamboo, bambooleaves, leaves, leavesbranchy, leavesnarrow, log, lognarrow, logsection
RainDrip - -
Reinforcable - -
RightClickPickup
  • dropsPickupMode (bool, default: false)
  • sound (path from sounds folder)
  • placeSound (path from sounds folder)
basereturnteleporter, bowl, bowl-meal, clayplanter, claypot, crock, crucible, egg, flowerpot, ingotmold, jug, lantern, looseflints, looseores, loosestick, loosestones, metal, oillamp, pan, pie, pineapple, pumpkin, seashell, storagevessel, toolmold, wateringcan, woodbucket
RopeTieable - roughhewnfence, woodenfence
Slab - -
Steaming - boilingwater
SneakPlacing - pan, pie, wateringcan
Unplaceable - bloomerychimney, bowl, bowl-meal, clayplanter, claypot, crock, crucible, flowerpot, ingotmold, jug, metal, pineapple, pumpkin, storagevessel, toolmold, wateringcan
Unstable
  • attachedToFaces (default: down)
  • attachmentAreas (side -> RotatableCube)
bunchocandles, crop, deadcrop, firepit, oreblastingbomb, silvertorchcactus, verticalboiler, wildbeehive, woodenpath, woodenrails
UnstableFalling
  • attachableFaces (string array)
  • attachmentArea (cuboid)
  • attachmentAreas (side -> RotatableCube)
  • ignorePlaceTest (bool, default: false)
  • exceptions (block code array)
  • fallSideways (bool, default: false)
  • dustIntensity (float, default: 0)
  • fallSidewaysChance (float, default: 0.3)
  • fallSound (path from sounds folder)
  • impactDamageMul (float, default 1)
anvil, anvilpart, barrel, barrelcactus, bloomerychimney, bonyremains, bonysoil, carcass, chair, chandelier, cheese, churn, clayplanter, coalpile, dirtygravel, displaycase, drycarcass, egg, flowerpot, gravel, groundstorage, ingotmold, knappingsurface, lightningrod, looseboulders, looseflints, loosegears, looseores, loosestick, loosestones, lootvessel, metal, metalpartpile, muddygravel, oillamp, omoktabletop, pan, pie, quern, sand, seashell, sieve, sludgygravel, snowlayer, stonecoffinlid, storagevessel, table, talldisplaycase, toolmold, wateringcan, woodbucket
WrenchOrientable
  • hideInteractionHelpInSurvival (bool, default: false)
  • baseCode (string)
banner, brickslabs, brickstairs, carvedlog, chute, clayshinglelabs, clayshinglestairs, clutter, cobblestoneslab, cobblestonestairs, debarkedlog, glassslab, jonas, log, mudbrickslab, planks, plankslab, plankstairs, plaster, polishedrockslab, quartzpillar, quartzslab, quartzstairs, stonebrickslab, stonebrickstairs, stonepathstairs
WorldEditFixGhostBlockPlace - -
Icon Sign.png

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.


BlockMaterial
string - A behavior adds custom abilities such as falling block.
Soil

Gravel

Sand

Wood

Leaves

Stone

Liquid

Snow

Ice

Metal

Mantle

Plant

Glass

Ceramic

Cloth

Lava

Brick

Fire

Other

Materials are hardcoded and currently only used to determine mining speed with a specific tool.

MatterState
array of object "block" Determines whether the block is in a solid, a liquid, a gas or a plasma state.
solid


liquid


gas


plasma


Used for special collision behavior and rendering. Currently used for:

Liquid:

  • Lava
  • Water
  • Water with particles

Gas/Plasma: none added yet

Resistance
decimal number 6 How long it takes to break this block in seconds (with a mining speed of 1).

Same examples of resistance's values used in VintageStory:

Block Value
leave 0.5
wool 1.0
bowl 1.5
obsidian 2
plank 3.5
log 4.5
rock 6
RequiredMiningTier
integer 0 Minimum required mining tier to get the drop out of the block.
Tier Ores
1 gelena and rocksalt_sylvite
2 lignite, cassiterite, sphalerite, rocksalt, sulfur and nativecopper
3 bituminouscoal, quartz_nativegold, quartz_nativesilver, lapislazuli, bismuthinite, quartz, magnetite and limonite
4 diamond and emerald
5 chromite, platinum and ilmenite
Climbable
boolean false If true, walking against this block will make the player climb (used for ladders).
RainPermeable
boolean false If rain can fall through this block.
SnowCoverage
boolean - Whether snow may rest on top of this block.

All none solid blocks can't be covered by snow unless it's defined different:

  • Leaves (also branchy): true,
  • Water with particles, Lakeice: false
CollisionBox
object box (0,0,0 -> 1,1,1) Defines a box with which the player collides with.

A half slab for example, has either a box going from 0,0,0 to 1,0.5,1 or going from 0,0.5,0 to 1,1,1, depending on whether it is a slab is down or up:

	collisionboxByType: {
		"*-down": { x1: 0, y1: 0, z1: 0,   x2: 1, y2: 0.5, z2: 1 },
		"*-up": { x1: 0, y1: 0.5, z1: 0,   x2: 1, y2: 1, z2: 1 }
	},

Collision and selection boxes are most likely equal.

CollisionBoxes
array of object - Defines multiple boxes with which the player collides with.

A crate for example requires multiple collision boxes:

	collisionboxesByType: {
		"*-opened": [ 
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.0625, z2: 1 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 90 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 180 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 270 },
		]
	},
SelectionBox
object box (0,0,0 -> 1,1,1) Defines a box which the player's mouse pointer collides with for selection.

A half slab for example, has either a box going from 0,0,0 to 1,0.5,1 or going from 0,0.5,0 to 1,1,1, depending on whether it is a slab is down or up:

	selectionboxByType: {
		"*-down": { x1: 0, y1: 0, z1: 0,   x2: 1, y2: 0.5, z2: 1 },
		"*-up": { x1: 0, y1: 0.5, z1: 0,   x2: 1, y2: 1, z2: 1 }
	},

Collision and selection boxes are most likely equal.

SelectionBoxes
array of object - Defines multiple boxes which the player's mouse pointer collides with for selection.

A crate for example requires multiple selection boxes:

	selectionboxesByType: {
		"*-opened": [ 
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 0.0625, z2: 1 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 90 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 180 },
			{ x1: 0, y1: 0, z1: 0, x2: 1, y2: 1, z2: 0.0625, rotateY: 270 },
		]
	},
Replaceable
integer 0 A value usually between 0-9999 that indicates which blocks may be replaced with others.
Value Effect (Blocks)
0 ordinary blocks (stone for example)
5000 Everything equal or above will be washed away by water (such as Fruit).
6000 Everything equal or above wwill replaced when the player tries to place a block (such as Tallgrass).
9000 Lava
9500 Water
9999 Air
Fertility
integer 0 Which plants can grow on top of this block.
Value Effect
0 nothing can grow.
10 some tallgrass and small trees can be grow on it.
100 all grass and trees can grow on it.
GlowLevel
0 ... 255 0 Causes the block to visually glow if Bloom is enabled. Basic glow level for all the blocks model elements.
Blocks Value
Glacierice 8
Paperlantern 32
Ember 48
Fire, Firepit, Oillamp, Torch 64
Lava 128
LightAbsorption
0 ... 32 0 For light blocking blocks. Any value above 32 will completely block all light.
WalkspeedMultiplier
decimal number 1.0 Percentage walk-speed when standing on or inside this block.
Blocks Value
Spiderweb 0.25
Stonepath 1.15
DragMultiplier
decimal number 1.0 Drag multiplier applied to entities standing on it (slipperiness factor).
Blocks Value
Glacierice, Lakeice 0.02
Drops
array of object - The items that should drop from breaking this block.

Drop itself

If this property does not exist the block will drop itself.


No drop

A firepit for example doesn't drop anything. You can do so if you specify an empty array:

	drops: [],

Special drop

You can also specify a special item/ block. 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, the drop of a charcoalpile looks like this:

	drops: [
		{ type: "item", code: "charcoal" }
	],

Tallgrass will only drop 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. Sapling 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:

dropsByType: {
	"ore-quartz-*": [
		{ type: "item", code: "clearquartz",  quantity: { avg: 0.2, var: 0 }, lastDrop: true },
		{ type: "item", code: "ore-{ore}",  quantity: { avg: 1.25, var: 0 }  }
	],
	"*": [ 
		{ type: "item", code: "ore-{ore}",  quantity: { avg: 1.25, var: 0 }  }
	],
}

Quartz ore will drop with a 20% chance clearquartz, if not it will drop the regular ore. If lastDrop wouldn't be true it could drop both at the same time.

ParticleProperties
array of object - Particles that should spawn in regular intervals from this block.

The torch is a good example of how to use those particles ...

	particleProperties: [
		{
			hsvaColor: [{ avg: 20, var: 20 }, { avg: 255, var: 50 }, { avg: 255, var: 50 },  { avg: 255, var: 0 }],
			gravityEffect: { avg: 0, var: 0 },
			posOffset: [ { avg: 0, var: 0.1 }, { avg: 0, var: 0 }, { avg: 0, var: 0.1 }],
			velocity: [ { avg: 0, var: 0.025 }, { avg: 0.5, var: 0.1 }, { avg: 0, var: 0.025 }],
			quantity: { avg: 0.015 },
			size: { avg: 0.5, var: 0 },
			sizeEvolve: { transform: "quadratic", factor: -0.7 },
			lifeLength: { avg: 1.5 },
			glowLevel: 64
		},
		{
			hsvaColor: [{ avg: 0, var: 0 }, { avg: 0, var: 0 }, { avg: 40, var: 30 },  { avg: 220, var: 50 }],
			opacityEvolve: { transform: "quadratic", factor: -16 },
			gravityEffect: { avg: 0, var: 0 },
			posOffset: [ { avg: 0, var: 0.1 }, { avg: 0, var: 0 }, { avg: 0, var: 0.1 }],
			velocity: [ { avg: 0, var: 0.025 }, { avg: 0.15, var: 0.1 }, { avg: 0, var: 0.025 }],
			quantity: { avg: 0.05 },
			size: { avg: 0.25, var: 0.05 },
			sizeEvolve: { transform: "linear", factor: 0.5 },
			particleModel: "Quad"
		}
	],

There is also a complete tutorial about particles, which should help you to find out what each property does.

LiquidLevel
0 ... 7 0 Value between 0...7 for Liquids to determine the height of the liquid.
CropProps
object - Information about the block as a crop.
Sounds
key: string, value: string - The sounds played for this block during step, break, build and walk.
Walk
An entity walks over it.
Inside
The player is inside the block.
Break
Breaking the block.
Place
Placing the block.
Hit
While mining the block.
Ambient
Played from time to time if the player is close to it.

Anvil:

    sounds: {
        "place": "block/anvil",
        "break": "block/anvil"
    }

Rails:

    sounds: {
        place": "block/planks",
        "walk": "walk/wood"
    }

Water:

    sounds: {
        place: "block/water",
        inside: "walk/water",
        ambient: "environment/creek"
    },
Common
CreativeInventory
key: string, value: string[] - In which creative inventory tabs the block should be visible in.

There are several tabs to you can add your stuff. Note that general should always be included, since it should contain everything.

  • general
  • terrain
  • flora
  • construction
  • decorative
  • items

Rock adds all of it's variantions to general, terrain and construction:

	creativeinventory: { "general": ["*"], "terrain": ["*"], "construction": ["*"] },

* reprents the variants which will be added. You can specify multiple and separate them with a comma. It follows the same way as the byType property.

A Torch on the other hand only adds the variation up:

	creativeinventory: { "general": ["*-up"], "decorative": ["*-up"] },
MaxStackSize
integer 64 Determines the maximum amount you can stack the block in one slot.
AttackPower
decimal number 0.5 The damage the deals when hitting an entity.
AttackRange
decimal number 1.5 The maximum distance you can hit an entity.
MaterialDensity
integer 9999 Determines on whether an object floats on liquids or not.

Water has a density of 1000, meaning everything below or equal will float on water. The same goes for lava which has a density of 5000.

LiquidSelectable
boolean false If the block can select a liquid while holding it in hand.

Used for buckets in order to fill it with water and to place waterlily on top of water.

MiningSpeed
key: string, value: decimal number - The mining speed for each material.
MiningTier
integer 0 Determines which blocks it can break. If the required miningtier is above the defined one there will be no drop from it.
Attributes
key: string, value: object - Custom Attributes associated with this block.

Extra attributes added to a block. Those are final and cannot be modified. It's a good way to keep things organized and and modifiable. The oreblastingbomb for example has attributes, which define its radius and type. These can be used by behaviors and blockentities:

    attributes: {
		"blastRadius": 4,
		"blastType": 0,
	},
CombustibleProps
object - Information about the blocks burnable states.
BurnTemperature
integer - The temperature at which it burns in degrees Celsius.
BurnDuration
decimal number - For how long it burns in seconds.
HeatResistance
integer 500 How many degrees celsius it can resists before it ignites (not implemented yet).
MeltingPoint
integer - How many degrees celsius it takes to smelt/transform this into another. Only used when put in a stove and SmeltedStack is set.
MeltingDuration
decimal number - For how many seconds the temperature has to be above the melting point until the item is smelted.
SmokeLevel
decimal number 1 How much smoke this item produces when being used as fuel.
SmeltedRatio
integer 1 How many ores are required to produce one output stack.
SmeltedStack
object - If set, the block/item is smeltable in a furnace and this is the resulting itemstack once the MeltingPoint has been reached for the supplied duration.
RequiresContainer
boolean true If set to true, the block/item requires a smelting/cooking/baking container such as the Crucible. If false, it can be directly baked/melted without smelting/cooking/baking container.

This property can be used to define a burning material. Plank for example can get on fire:

    combustibleProps: {
        burnTemperature: 800,
        burnDuration: 12,
    },

Furthermore it can be used to define smelting processes. An example would be an ingotmold which turns into an ingotmold-burned:

    combustiblePropsByType: {
        "ingotmold-raw": {
            meltingPoint: 600,
            meltingDuration: 30,
            smeltedRatio: 1,
            smeltedStack: { type: "block", code: "ingotmold-burned" },
            requiresContainer: false
        }
    },
NutritionProps
object - Information about the blocks nutrients.
FoodCategory
string - Defines the type of food. It can be fruit, vegetable, protein, grain and dairy.
Saturation
decimal number 0 How much saturation it can restore.
Health
decimal number 0 How much health it can restore.
Rendering
Textures
key: string, value: object The texture definitions for the block as seen in the world, when dropped on the ground or held in the hand.
base


overlays


alternates
The dictionary contains multiple named textures. Different tessellators expect different texture names. Most tessellators accept the special "all" alias to set all textures at once. Default example (glass):
textures: {
		all: { base: "block/glass" },
	}
Using variantgroups (rock):
textures: {
		all: {base: "block/stone/rock/{rock}" },
	}

There are a few aliases that set multiple textures at the same time:

  • all - sets all textures for tessellators that support the alias
  • sides - "west", "east", "north", "south", "up", and "down"
  • horizontals - "west", "east", "north", and "south"
  • verticals - "up" and "down"
  • westeast - "west" and "east"
  • northsouth - "north" and "south"

For example, hay block uses two aliases:

textures: {
		horizontals: { base: "block/hay/{type}-side" },
		verticals: { base: "block/hay/{type}-top" },
	},
There are many options to rotate textures, combine them, and randomize the textures by block location.
TexturesInventory
key: string, value: object The texture definitions for the block as seen in the player inventory. Overrides the textures.
Shape
object - For the json drawtype, the shape definition of the block as shown in the world, dropped on the ground or held in hand.
base
The path to the shape json file, the base dir is assets/shapes/.
rotateX
float 0 Only 90 degree rotations are possible.
rotateY
float 0 Only 90 degree rotations are possible.
rotateZ
float 0 Only 90 degree rotations are possible.
ShapeInventory
object - For the json drawtype, the shape definition of the block as shown in the players inventory.
DrawType
string "cube" Determines how the block is tesselated, select JSON for being able to use custom JSON Models. The other values are hardcoded methods of tesselating the block.
blockLayer_1
0
blockLayer_2
1
blockLayer_3
2
blockLayer_4
3
blockLayer_5
4
blockLayer_6
5
blockLayer_7
6
json
7 Will draw a json model.
empty
8 Nothing will be drawn.
cube
9 Draws an ordinary cube.
cross
10
transparent
11
liquid
12
crossandsnowlayer
13
RenderPass
string "opaque" Determines how the block will be drawn.
opaque
0 Used for solid blocks with no half transparency.
opaquenocull
1 Used for non-solid single faced blocks, such as tall grass.
transparent
2 Use for solid halftransparent blocks, such as glass
liquid
3 Used for liquids, produces waves.
topsoil
4 Used for grass covered blocks. Allows for a smooth transition from grass to soil, while still allowing climate tinting of grass.
AmbientOcclusion
boolean true If ambient occlusion will be applied to the block.
TintIndex
integer 0 0 for no tint, 1 for plant climate tint, 2 for water climate tint.
RenderFlags
0 ... 255 0 8 bits that are sent to the graphics card for each vertex of the blocks shape. The lower 3 bits are currently used for altering the vertexes z-depth to fix a bunch of z-fighting issues.
FaceCullMode
string "default" Determines which sides of the blocks should be rendered.
Default
0 Culls faces if they are opaque faces adjacent to opaque faces.
NeverCull
1 Never culls any faces.
Merge
2 Culls all faces that are adjacent to opaque faces and faces adjacent to blocks of the same id (Example usage: Ice blocks).
Collapse
3 Culls all faces that are adjacent to opaque faces and the bottom, east or south faces adjacent to blocks of the same id. This causes to still leave one single face in between instead of 2, eliminating any z-fighting.
MergeMaterial
4 Same as Merge but checks for equal material (Example usage: Plain glass and all colored glass blocks).
CollapseMaterial
5 Same as Collapse but checks for equal material (Example usage: All leaves blocks).
Liquid
6 Same as CollapseMaterial but also culls faces towards opaque blocks.
SideOpaque
key: string, value: boolean - Determines if given block face is fully opaque. If yes, the opposite face of the adjacent block will not be drawn for efficiency reasons.
all

horizontals

verticals

east

west

up

down

north

south
SideAo
key: string, value: boolean - If AmbientOcclusion will be applied for each side.
all

horizontals

verticals

east

west

up

down

north

south
SideSolid
key: string, value: boolean - Determins if given block side is solid. If true, other blocks like torches can be attached to it.
all

horizontals

verticals

east

west

up

down

north

south
RandomDrawOffset
boolean false If true then the block will be randomly offseted by 1/3 of a block when placed.
LightHsv
byte array with 3 elements. See http://tyron.at/vs/vslightwheel.html for valid values - For light emitting blocks: hue, saturation and brightness value.
LightAbsorption
0 ... 255 99 For light blocking blocks. Any value above 32 will completely block all light.
GuiTransform
object block default Used for scaling, rotation or offseting the block when rendered in guis.
FpHandTransform
object block default Used for scaling, rotation or offseting the block when rendered in the first person mode hand.
TpHandTransform
object block default Used for scaling, rotation or offseting the block when rendered in the third person mode hand.
GroundTransform
object block default Used for scaling, rotation or offseting the rendered as a dropped item on the ground.
RandomizeAxes
string "xyz" Random texture selection - whether or not to use the Y axis during randomization (for multiblock plants).
XYZ
0
XZ
1


Icon Sign.png

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.