Modding:Block Cardinality

There are several objects related to the representation of a block. This page compares the number of instances of those different representations.

There are millions of andesite rock blocks in the game world. It would be memory inefficient to create a C# class object for every one of those blocks. So instead the common properties of those andesite rock blocks are factored out into a block type. That block type is assigned a unique integer in the game world. So the game world stores the blocks as a big 3d dimensional array of integers (each integer is a block id). Whenever the block receives an event (for example it is broken), the block id is converted to the block type, and an event handler is called on that block type. Since all blocks of that type share the same block type, the event handler is given the coordinates of the block so that the block handler can determine exactly which block of that type is being broken.

Note on terminology

The term block is overloaded. In the player documentation, block refers to an object placed in the world. If two blocks have different coordinates, the blocks are always considered unique, even if they are the same type of block. However, most of the modding documentation uses the term 'block' as an abbreviation for block type. For clarity, the rest of this page does not use block as abbreviation for block type.

As an example, let's say the player has a stack of 10 andesite rocks, and the player places each of those rocks at different coordinates in the game. 10 blocks were placed, and they all have the same block type. Some of the modding documentation would say the same block was placed 10 times, where in that page block actually refers to the block type.

Block object is used a synonym for block type.

Also note that the term block type is distinct from Vintagestory.ServerMods.NoObf.BlockType. That BlockType is created temporarily while parsing a json block file. Since it is a well abstracted implementation detail of parsing the json block file, most documentation does not reference it.

Cardinalities

The below table uses the A concept : B concept to describe the ratio between different concepts. The first part is the ratio antecedent and the second is the ratio consequent. The notation means that A instances of concept A map to B instances of concept B. The C..D notation is used when there are a range of possible values for a side of the ratio. 0..* describes the range 0 to infinity; that is any values is possible for that side of the ratio.

Ratio antecedent	Ratio consequent	Description
1 json block file	0..* block types	A block json file can describe multiple variants of the block, but it must describe at least 1. Each block variant is also called a block type.
1 block type	1 block code	Each block type has a block code. A block code is specifically an instance of AssetLocation that refers to the fully resolved block. An example is game:log-placed-oak-ud. Each dash separated component of the block code is the value for the corresponding variant group of the block.
	0..* block behaviors	The block behaviors are listed in the behaviors field of the json block file. A behavior is an instance of a class that inherits from BlockBehavior. If different block types reference the same block behavior, then different instances of that BlockBehavior are created (BlockBehavior instances are not shared between block types). It is possible for different variants of the block to have different lists of block behaviors.
	0..1 block entity classes	Simple block types do not block entities associated with them. However, complicated block types may have exactly 1 block entity class, which is specified through the entityClass field.
	0..* block entity behavior specifications	If the block type has a block entity, then it may also specify block entity behaviors. However, these are only specifications, because the block entity behaviors are not created until the actual blocks are created.
	0..* blocks	For every block type, there can be any number of blocks placed in the game that use that type.
1 block	0..1 block entities	If the block type has a block entity class, then each block of that type will have exactly 1 block entity (instance of a class that inherits from BlockEntity). For block types that do not specify a block entity, their blocks will have 0 block entities.
1 block entity	0..* block entity behaviors	If the block type specified a list of block entity behaviors, then an instance of each of those behaviors (instance of a class that inherits from BlockEntityBehavior) will be created for all of its every block entities. Block behaviors are not shared between block entities.
1 block code	1 block id	The first time the game world discovers a block code, it is assigned a block id, which is an integer. The mapping of block ids to block codes is persistent for each game world, but the mapping can vary between game worlds, if the game worlds happen to load reference the block types for the first time in a different order.
1 block class	0..* block types	A block class is a class that inherits from VintageStory.API.Common.Block. A block type is an instance of a block class. The class of a block is specified through the class field in the json block file. It defaults to VintageStory.API.Common.Block itself. It is possible for a block class to have 0 block types if none of the json files reference it.

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.