voxelcoreprojects/voxelcore
1
0
Fork 0
mirror of https://github.com/MihailRis/voxelcore.git synced 2026-10-04 18:41:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
voxelcore/doc/en/vcm.md
MihailRis 60f74ae54a update doc/*/vcm.md
2026-09-25 20:39:22 +03:00

5.4 KiB
Raw Blame History

VCM

A text format for describing 3D models, replacing the deprecated model-primitives property.

Syntax:

@primitive attribute (value1, value2,...) attribute2 "value3" {
    @inner_primitive ...
}

Same structure in XML:

<primitive attribute="value1, value2,..." attribute2="value3">
    <inner_primitive .../>
</primitive>

Unlike XML, the root can contain multiple elements.

Currently, there are three types of primitives: tri, box, rect and part (describes a part of a primitive, such as the side of a cube).

Note

By default, texture coordinates are determined by the dimensions of the primitives. For sizes greater than 1.0, the result is undefined and may change in future updates. Use region or region-scale for manual adjustments.

Primitives

tri Properties

This primitive describes a triangle.

  • a - Point A. Example: a (0,0,0)
  • b - Point B. Example: b (1,0,0)
  • c - Point C. Example: c (1,1,0)
  • uv - Normalized texture coordinates of the points (6 numbers, 2 per point). Example: uv (0,0,1,0,1)
  • texture - The texture to display. Default: $0. Example: texture "blocks:sand"
  • region - UV region within the selected texture, defined by the positions of opposite corners of a square of normalized texture coordinates. Example: region (0,0,1,1)
  • region-scale - multiplier vector for the UV region. Example: region-scale (0.5,1)
  • shading - determines whether shading is enabled on the primitive. Example: shading off
  • normal - overrides normal vector. Example: normal (0,1,0)
  • cull-face - determines which side will be culled. Example: cull-face front or cull-face off (disables face culling)

By default, texture coordinates are not affected by shape or size, unlike other primitives.

rect Properties

This primitive describes a parallelogram using the right and up vectors.

  • from - the origin of the primitive. Example: from (0,0.5,0.125)
  • right - the X vector, which also determines the width of the primitive. Example: right (1,0,0)
  • up - the Y vector, which also determines the primitive's height. Example: up (0,1,0)
  • texture - the texture to display. Default: $0. Example: texture "blocks:sand"
  • region - the UV region within the selected texture, defined by the positions of opposite corners. Example: region (0,0,1,1)
  • region-scale - the multiplier vector for the automatically selected UV region. Example: region-scale (0.5,1)
  • shading - determines whether shading is enabled on the primitive. Example: shading off
  • flip - flips the UV region horizontally or vertically. Example: flip v
  • normal - overrides normal vector. Example: normal (0,1,0)
  • cull-face - determines which side will be culled. Example: cull-face front or cull-face off (disables face culling)

box Properties

This primitive describes a rectangular parallelepiped.

  • from - the primitive's origin. Example: from (0,0,0)
  • to - the point opposite the origin. Example: to (1,1,1)
  • origin - the point relative to which the rotation will be applied. Default: the center of the primitive. Example: origin (0.5,0.5,0.5)
  • rotate - rotation around the (x,y,z) axes in degrees, or a quaternion (x,y,z,w). Example: rotate (45,0,0) or rotate (0.3826834, 0, 0, 0.9238795)
  • texture - the default texture to display for all sides.
  • shading - determines whether shading is enabled on the primitive. Example: shading off
  • delete - deletes sides by name (top, bottom, east, west, north, south)

part properties (nested in box)

This primitive describes the properties of the sides of a rectangular parallelepiped with the specified tags (top/bottom/north/south/east/west).

  • tags - determines which side the properties will be applied to. Example: tags (top,bottom)
  • texture - the texture to display. Default: $side_index.
  • region - the UV region within the selected texture, defined by the positions of opposite corners. Example: region (0,0,1,1)
  • region-scale - multiplier vector for the automatically selected UV region. Example: region-scale (0.5,1)

Skeleton

VCM can describe the skeleton of a model. The @bone element is used for this.

There are two types of bones:

  • unnamed - used only for transformations on inner primitives and not included in the final skeleton.
  • named - will be included in the final skeleton. The name is specified via the name attribute.

The main bone (root) is created automatically for the entire model. If bones are explicitly specified, the model will be divided into several parts named as model_name.bone_name. Since the model is an asset and has no prefix, the loaded skeleton receives the model name, also without a prefix. The loaded skeleton can be used in the entity via the skeleton-name property.

In the pack/preload.json list, if "squash": true is specified, the vcm will be loaded as a single model, without a skeleton.

bone Properties

  • name - The bone name. If omitted, the bone will be "dissolved" and will not be included in the final skeleton, but transformations will be applied.
  • move - Moves nested elements.
  • scale - Scales nested elements. Applied before moving.
  • rotate - Rotates nested elements around the (x, y, z) axes in degrees, or as a quaternion (x, y, z, w). Example: rotate (45,0,0) or rotate (0.3826834, 0, 0, 0.9238795)