Texture Packs

Texture Packs

ZigCraft supports custom texture packs, allowing you to replace the default block textures with your own, including HD texture packs and PBR (Physically Based Rendering) materials.

Quick Start

1. Create a new folder in assets/textures/ with your pack name (e.g., assets/textures/my-pack/)
2. Add your PNG textures to the folder
3. Launch the game and select your pack from the TEXTURE PACKS menu (accessible from the main menu)

Texture Requirements

• Format: PNG (32-bit RGBA recommended)
• Size: Any power-of-two size is supported:
  • 16x16 (default)
  • 32x32
  • 64x64
  • 128x128
  • 256x256
  • 512x512 (HD)
• Naming: Use the exact filenames listed below
• Consistency: All textures in a pack should be the same resolution for best results

Folder Structure Options

ZigCraft supports two folder structures:

Option 1: Flat Structure (Legacy/Simple)

assets/textures/my-pack/
├── stone.png
├── dirt.png
├── grass_top.png
├── grass_side.png
└── ...

Option 2: PBR Subfolder Structure (Advanced)

For PBR texture packs with normal maps, roughness, and displacement:

assets/textures/my-pbr-pack/
├── stone/
│   ├── stone.png          # or stone_diff.png (diffuse/albedo)
│   ├── stone_nor_gl.png   # Normal map (OpenGL format)
│   ├── stone_rough.png    # Roughness map
│   └── stone_disp.png     # Displacement map
├── dirt/
│   ├── dirt.png
│   ├── dirt_nor_gl.png
│   ├── dirt_rough.png
│   └── dirt_disp.png
├── grass_top/
│   ├── grass_top.png
│   └── ...
└── ...

PBR Map Types

Map Type	Suffix	Description
Diffuse/Albedo	_diff.png or .png	Base color of the material
Normal Map	_nor_gl.png or _normal.png	Surface detail (OpenGL format: Y+ is up)
Roughness	_rough.png or _roughness.png	How rough/smooth the surface is (white = rough, black = smooth)
Displacement	_disp.png or _height.png	Height/depth information for parallax effects

Note: Normal maps should be in OpenGL format (green channel points up). DirectX format normal maps will appear inverted.

Texture Filename Reference

The following table shows which PNG filenames correspond to each block type. Alternative filenames are also accepted for compatibility with Minecraft resource packs.

Basic Blocks

Block Type	Primary Filename	Alternatives
Stone	stone.png	-
Dirt	dirt.png	-
Grass (top)	grass_top.png	grass_carried.png, grass_block_top.png
Grass (side)	grass_side.png	grass_side_carried.png, grass_block_side.png
Sand	sand.png	-
Cobblestone	cobblestone.png	-
Bedrock	bedrock.png	-
Gravel	gravel.png	-
Glass	glass.png	-
Water	water.png	water_still.png

Ores & Resources

Block Type	Primary Filename	Alternatives
Coal Ore	coal_ore.png	-
Iron Ore	iron_ore.png	-
Gold Ore	gold_ore.png	-
Clay	clay.png	-
Glowstone	glowstone.png	-

Wood Types

Oak Wood

Block Type	Primary Filename	Alternatives
Oak Log (side)	wood_side.png	oak_log.png, log_oak.png
Oak Log (top)	wood_top.png	oak_log_top.png, log_oak_top.png
Oak Leaves	leaves.png	oak_leaves.png, leaves_oak.png

Jungle Wood

Block Type	Primary Filename	Alternatives
Jungle Log (side)	jungle_log_side.png	log_jungle.png
Jungle Log (top)	jungle_log_top.png	log_jungle_top.png
Jungle Leaves	jungle_leaves.png	-

Acacia Wood

Block Type	Primary Filename	Alternatives
Acacia Log (side)	acacia_log_side.png	log_acacia.png
Acacia Log (top)	acacia_log_top.png	log_acacia_top.png
Acacia Leaves	acacia_leaves.png	-
Acacia Sapling	acacia_sapling.png	sapling_acacia.png

Mangrove Wood

Block Type	Primary Filename	Alternatives
Mangrove Log (side)	mangrove_log_side.png	-
Mangrove Log (top)	mangrove_log_top.png	-
Mangrove Leaves	mangrove_leaves.png	-
Mangrove Roots	mangrove_roots.png	-

Environment Blocks

Block Type	Primary Filename	Alternatives
Snow	snow_block.png	snow.png
Mud	mud.png	-
Cactus (side)	cactus_side.png	-
Cactus (top)	cactus_top.png	-
Melon (side)	melon_side.png	-
Melon (top)	melon_top.png	-
Bamboo	bamboo.png	bamboo_stem.png
Terracotta	terracotta.png	hardened_clay.png
Red Sand	red_sand.png	-

Mushroom Biome

Block Type	Primary Filename	Alternatives
Mycelium (top)	mycelium_top.png	-
Mycelium (side)	mycelium_side.png	-
Mushroom Stem	mushroom_stem.png	mushroom_block_skin_stem.png
Red Mushroom Block	red_mushroom_block.png	mushroom_block_skin_red.png
Brown Mushroom Block	brown_mushroom_block.png	mushroom_block_skin_brown.png

Plants & Decorations

Block Type	Primary Filename	Alternatives
Tall Grass	tall_grass.png	tallgrass.png
Red Flower	flower_red.png	flower_rose.png, poppy.png
Yellow Flower	flower_yellow.png	flower_dandelion.png, dandelion.png
Dead Bush	dead_bush.png	deadbush.png

Special Notes

Grass Block Textures

Grass blocks use three textures:

• Top face: Uses grass_top.png with biome tinting applied
• Side faces: Uses grass_side.png (should show grass at top, dirt below)
• Bottom face: Uses dirt.png

Biome Tinting

The following blocks receive biome-based color tinting:

• Grass (top face only)
• All leaf types (oak, jungle, acacia, mangrove)
• Tall grass
• Water

Fallback Behavior

If a texture file is not found in your pack, ZigCraft will:

1. Try alternative filenames (if any)
2. Fall back to a solid color based on the block type

VRAM Usage by Resolution

Tile Size	Atlas Size	Approx. VRAM (Diffuse Only)	Approx. VRAM (Full PBR)
16x16	256x256	~256 KB	~1 MB
32x32	512x512	~1 MB	~4 MB
64x64	1024x1024	~4 MB	~16 MB
128x128	2048x2048	~16 MB	~64 MB
256x256	4096x4096	~64 MB	~256 MB
512x512	8192x8192	~256 MB	~1 GB

PBR Lighting

When PBR textures are detected, ZigCraft uses physically-based rendering with:

• Cook-Torrance BRDF for specular reflections
• GGX/Trowbridge-Reitz normal distribution
• Schlick-GGX geometry function
• Schlick approximation for Fresnel
• Reinhard tone mapping and gamma correction

This provides more realistic lighting with:

• Proper specular highlights based on roughness
• Surface detail from normal maps
• Energy conservation

Hot Reloading

Texture packs can be switched at runtime through the in-game menu. Changes take effect immediately without restarting the game.