Modding:Textures

This page was last verified for Vintage Story version 1.19.

Before customizing textures, it's suggested you read the Basic Item, Basic Block and Basic Entity pages first in order to understand this tutorial. This tutorial describes how to apply textures to items, blocks, and entities. In addition to this tutorial, there is a reference for all of the fields within a texture.

Texturing an Item

Flat Texturing

Texturing your items and blocks in vintage story is quite simple, but there's some things to consider when using shapes. Lets start off with just using a flat texture for an item:

texture: { base: "item/resource/texture" }

If your item has a variant you can also use it in the textures, even without the byType function:

texture: { base: "path to texture/texture-{variant}" }

Shape Texturing

If your item is rendered with a custom shape using shape: { base: "path to shape" } you can control it's textures using the plural version "textures". Doing so requires that you use the same "#texture" identifier used on each side of a shape cube.

Lets see an example. First we'll look at a few cubes in a shape JSON:

{
  "name": "Cube_1",
  "from": [ 0.5, 0.0, 2.0 ], 
  "to": [ 5.5, 1.0, 2.5 ], 
  "rotationOrigin": [ 1.0, 0.0, -1.0 ],
  "faces": {
    "north": { "texture": "#metal", "uv": [ 0.0, 0.0, 5.0, 1.0 ] },
    "east": { "texture": "#metal", "uv": [ 7.0, 3.0, 7.5, 4.0 ] },
    "south": { "texture": "#metal", "uv": [ 1.0, 2.0, 6.0, 3.0 ] },
    "west": { "texture": "#metal", "uv": [ 7.0, 0.0, 7.5, 1.0 ] },
    "up": { "texture": "#metal", "uv": [ 0.0, 3.0, 5.0, 3.5 ] },
    "down": { "texture": "#metal", "uv": [ 0.0, 0.0, 5.0, 0.5 ] }
  }
}
{
  "name": "Cube_2",
  "from": [ 0.5, 0.0, 2.0 ], 
  "to": [ 5.5, 1.0, 2.5 ], 
  "rotationOrigin": [ 1.0, 0.0, -1.0 ],
  "faces": {
    "north": { "texture": "#wood", "uv": [ 0.0, 0.0, 5.0, 1.0 ] },
    "east": { "texture": "#wood", "uv": [ 7.0, 3.0, 7.5, 4.0 ] },
    "south": { "texture": "#wood", "uv": [ 1.0, 2.0, 6.0, 3.0 ] },
    "west": { "texture": "#wood", "uv": [ 7.0, 0.0, 7.5, 1.0 ] },
    "up": { "texture": "#wood", "uv": [ 0.0, 3.0, 5.0, 3.5 ] },
    "down": { "texture": "#wood", "uv": [ 0.0, 0.0, 5.0, 0.5 ] }
  }
}

Now we can assign the #texture references from our item or block JSON using this format, which can also utilize variants in the regular {variant} format:

"textures": {
  "metal": {"base": "path to metal texture" },
  "wood": {"base": "path to wood texture" }
},

This is a useful method since both "metal" and "wood" can be assigned to multiple cubes within the shape JSON.

Voxelized Texture Shapes

If you decide you want a variant of an item to not be rendered using a JSON shape you can use the voxelizeTexture property when defining a shape. For example, an older version of the redmeat.json itemtype contains:

"shapebytype": { 
  "redmeat-vintage": { "base": "item/empty", "voxelizeTexture": true },
  "*": { "base": "item/food/meat/red" },
},
"texturesbytype": {
  "redmeat-raw": { 
    "meat": {"base": "item/food/meat/raw" }
  },
  "redmeat-cooked":  { 
    "meat": {"base": "item/food/meat/cooked" }
  },
  "redmeat-cured":  { 
    "meat": {"base": "item/food/meat/cured" }
  },
  "redmeat-vintage": {
    "item/empty":  { "base": "item/food/meat/vintage" }
  }
},

We can see here that only the "vintage" variant will be rendered as a regular voxelized item texture, while the rest will use the redmeat shape and apply their texture to it.

Texturing a Block

Simple Block

Blocks are textured a little differently since they default to generic "cube" shape. This means they don't use the singular "texture" method, and instead always use a version of the plural "textures":

"textures": {
  "all": {"base": "path to texture*"}
},

Texturing Other Block Faces

When assigning textures "all" will give every side the same texture, but we can easily customize each side, especially if we want to use some block behaviors like "Pillar" or "HorizontalOrientable":

"textures": {
  "up": { "base": "path to top texture" },
  "down": { "base": "path to bottom texture" },
  "south": { "base": "path to back texture" },
  "north": { "base": "path to front texture" },
  "west": { "base": "path to left texture" },
  "east": { "base": "path to right texture" },
},

Keep in mind that if you're using the "Pillar" or "HorizontalOrientable" behaviors you'll need directional variants for each (such as updown, northsouth, eastwest etc.) and you'll likely have to organize it using the ByType functionality. Great examples of these are the log.json (Pillar) and altar.json (HorizontalOrientable) blocktypes.

Texturing an Entity

Basic Entity Texture

All entities utilize a shape, but generally they are applied using a single entity map texture, which is essentially a texture file with each cube side mapped onto it. Doing this manually would be incredibly tedious, and is best done with the Vintage Story Model Builder found here.

Once you have your properly mapped out texture you can assign it to your entity:

texture: { base: "path to texture map" }

Alternative Entity Textures

After defining the first texture, you can also add alternatives to the same entity. For example, in the wolf-male.json entitytype:

"texture": { "base": "entity/wolf/wolf1", "alternates": [ { "base": "entity/wolf/wolf2" }, { "base": "entity/wolf/wolf2" }, {...} ] }

Each successive alternative should be numbered (starting with 1). Entities choose a random texture when they spawn for the first time.

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.