vintage_schematics/formats/

schematic.rs

//! Schematica format support.

use std::io::Read;

use eyre::{Context, bail, eyre};
use serde::{Deserialize, Serialize};
use tracing::debug;

use crate::{
	Map,
	convert::block::{FENCE_PATTERN, STAIR_PATTERN},
	formats::{
		Loadable, ToInternal,
		common::{MODERNISED_BLOCKS, MinecraftBlockEntity, Size},
		internal::{Block, BlockCodes, Internal, MinecraftBlockCode, PropertyMap},
		read, should_reject,
	},
};

const WOOD_VALUES: [&str; 6] = ["oak", "spruce", "birch", "jungle", "acacia", "dark_oak"];

const COLOURS: [&str; 16] = [
	"white",
	"orange",
	"magenta",
	"light_blue",
	"yellow",
	"lime",
	"pink",
	"gray",
	"light_gray",
	"cyan",
	"purple",
	"blue",
	"brown",
	"green",
	"red",
	"black",
];

/// South, west, north, east.
///
/// Used as an input to `data_facing` for fence gates and beds.
const DIRS_SWNE: [&str; 4] = ["south", "west", "north", "east"];

/// North, south, west, east.
///
/// Used as an input to `data_facing` for signs and chests.
const DIRS_NSWE: [&str; 4] = ["north", "south", "west", "east"];

/// East, west, south, north.
///
/// Used as an input to `data_facing` for torches and stairs.
const DIRS_EWSN: [&str; 4] = ["east", "west", "south", "north"];

/// The [Schematic](https://minecraft.wiki/w/Schematic_file_format) format.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "PascalCase")]
pub struct Schematic {
	/// Schematic size.
	#[serde(flatten)]
	pub size: Size,

	/// Block IDs.
	/// The block's code can be found in the `schematica_mapping` map.
	pub blocks: Vec<u8>,

	/// Additional [block data](https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Data).
	pub data: Vec<u8>,

	/// Block entity data.
	pub tile_entities: Vec<MinecraftBlockEntity>,

	/// Mapping of block names to IDs.
	/// Used with the `blocks` field.
	pub schematica_mapping: Map<String, u16>,

	/// The schematic's material version.
	/// Only "Alpha" is currently supported.
	pub materials: String,
}

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum CacheState {
	Rejected,
	Unseen,
	Cached(u16),
}

impl Loadable for Schematic {
	fn load(reader: impl Read, compressed: bool) -> eyre::Result<Self>
	where
		Self: Sized,
	{
		let mut schematic: Self = read(reader, compressed).context("failed to load schematic")?;

		if schematic.materials != "Alpha" {
			bail!("unsupported schematic material version: expected 'Alpha', found '{}'", schematic.materials);
		}

		if schematic.blocks.len() != schematic.data.len() {
			bail!(
				"blocks and data arrays have different lengths ({}, {})",
				schematic.blocks.len(),
				schematic.data.len()
			);
		}

		schematic.modernise();

		Ok(schematic)
	}

	fn modernise(&mut self) {
		for (old, new) in MODERNISED_BLOCKS {
			if let Some(value) = self.schematica_mapping.remove(*old) {
				self.schematica_mapping.insert(new.to_string(), value);
			}
		}
	}
}

impl ToInternal for Schematic {
	fn to_internal(self) -> eyre::Result<Internal> {
		// block codes
		// we can't convert these all in one go because they need to be paired with the data values from self.data
		let mut block_codes: Vec<MinecraftBlockCode> = Vec::with_capacity(self.schematica_mapping.len());

		// vec of block IDs to names
		// block IDs are eight-bit ints, so there can only be 256 possible values
		let mut names: Box<[Option<&str>; 256]> = Box::new([None; 256]);
		for (name, &id) in &self.schematica_mapping {
			if u8::try_from(id).is_ok() {
				// should always be the case
				names[id as usize] = Some(name);
			}
		}

		// data values are four-bit ints.
		// this means there are (eight for block ID) + (four for data) = twelve bits of data, or 4096 possible values.
		// set up a cache for them
		let mut cache = Box::new([CacheState::Unseen; 4096]);

		// converted blocks
		let mut blocks = Vec::with_capacity(self.blocks.len());

		// index of the air block, which is probably zero
		let air = self.schematica_mapping.iter().find(|(k, _)| **k == "minecraft:air").map(|(_, v)| *v);

		for (i, (block, data)) in (0..=i32::MAX).zip(self.blocks.into_iter().zip(self.data)) {
			if air.is_some_and(|a| a == u16::from(block)) {
				continue;
			}

			let id = if data < 16 {
				let cache_idx = ((block as usize) << 4) | data as usize;
				let cached = cache[cache_idx];

				match cached {
					CacheState::Rejected => continue,
					CacheState::Unseen => {
						// convert
						let name = names[block as usize].ok_or_else(|| eyre!("unknown block ID: {}", block))?;
						let code = convert_block(name, data)?;

						if should_reject(&code) {
							// remember that we've rejected this pair so we don't bother converting it again later
							cache[cache_idx] = CacheState::Rejected;
							continue;
						}

						// multiple (block, data) pairs can share the same code, so we should check to see if this code is a repeat.
						// if it isn't, we need to insert it
						let id = block_codes.iter().position(|c| c == &code).unwrap_or_else(|| {
							block_codes.push(code);
							block_codes.len() - 1
						});

						#[allow(clippy::cast_possible_truncation)]
						let cached = id as u16;
						cache[cache_idx] = CacheState::Cached(cached);

						id
					}
					CacheState::Cached(id) => id as usize,
				}
			} else {
				bail!("data value for block {i} out of range: expected 0-15, got {}", data);
			};

			blocks.push(Block {
				id,
				position: self.size.index_position(i),
			});
		}

		Ok(Internal {
			block_codes: BlockCodes::Minecraft(block_codes),
			blocks,
			tile_entities: self.tile_entities,
			size: self.size.into(),
		})
	}
}

fn convert_block(name: &str, data: u8) -> eyre::Result<MinecraftBlockCode> {
	// convert data to properties if necessary
	let (name, properties) = match name {
		"minecraft:torch" | "minecraft:redstone_torch" => convert_torch(name, data)?,
		"minecraft:leaves" => convert_leaves(data, false),
		"minecraft:leaves2" => convert_leaves(data, true),
		"minecraft:standing_sign" => convert_sign(data, false)?,
		"minecraft:wall_sign" => convert_sign(data, true)?,
		"minecraft:chest" => convert_chest(data)?,
		"minecraft:log" => convert_log(data),

		// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Wood_Planks
		"minecraft:planks" => (format!("minecraft:{}_planks", WOOD_VALUES.get(data as usize).unwrap_or(&"oak")), None),

		"minecraft:bed" => convert_bed(data)?,

		// colourful blocks
		"minecraft:wool" => convert_colourful("wool", data),
		"minecraft:stained_hardened_clay" => convert_colourful("terracotta", data),
		"minecraft:carpet" => convert_colourful("carpet", data),
		"minecraft:stained_glass" => convert_colourful("stained_glass", data),
		"minecraft:stained_glass_pane" => convert_colourful("stained_glass_pane", data),

		_ => {
			if name.ends_with("_gate") && FENCE_PATTERN.is_match(name) {
				convert_gate(data, name)?
			} else if name.ends_with("_stairs") && STAIR_PATTERN.is_match(name) {
				convert_stairs(name, data)?
			} else {
				if tracing::enabled!(tracing::Level::DEBUG) {
					debug!("passthrough: {name} with {data} ({data:#08b})");
				}
				(String::from(name), None)
			}
		}
	};

	let properties = properties.unwrap_or_default();
	let code = MinecraftBlockCode { name, properties };
	Ok(code)
}

fn convert_torch(name: &str, data: u8) -> eyre::Result<(String, Option<PropertyMap>)> {
	// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Torches_and_Redstone_Torches
	let redstone = name == "minecraft:redstone_torch";

	Ok(if data == 5 {
		(String::from(name), None)
	} else {
		let facing = data_facing(data, DIRS_EWSN, 1)?;

		let torch = if redstone {
			"minecraft:redstone_wall_torch"
		} else {
			"minecraft:wall_torch"
		};

		(String::from(torch), Some(Map::from([(String::from("facing"), facing.to_string())])))
	})
}

fn convert_leaves(data: u8, group_2: bool) -> (String, Option<PropertyMap>) {
	// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Leaves
	let leaf_array = if group_2 {
		&["acacia", "dark_oak", "oak", "oak"]
	} else {
		&WOOD_VALUES[0..4]
	};

	let leaf_type = leaf_array[(data & 0b11) as usize];
	(format!("minecraft:{leaf_type}_leaves"), None)
}

fn convert_sign(data: u8, wall: bool) -> eyre::Result<(String, Option<PropertyMap>)> {
	let properties = if wall {
		(String::from("facing"), data_facing(data, DIRS_NSWE, 2)?.to_string())
	} else {
		(String::from("rotation"), data.to_string())
	};

	let name = if wall {
		"minecraft:oak_wall_sign"
	} else {
		"minecraft:oak_sign"
	};

	Ok((String::from(name), Some(Map::from([properties]))))
}

fn convert_bed(data: u8) -> eyre::Result<(String, Option<PropertyMap>)> {
	// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Beds
	let facing = data_facing(data, DIRS_SWNE, 0)?;
	let part = if data & 0b1000 != 0 { "head" } else { "foot" };

	Ok((
		String::from("minecraft:red_bed"),
		Some(Map::from([(String::from("facing"), facing.to_string()), (String::from("part"), part.to_string())])),
	))
}

fn convert_chest(data: u8) -> eyre::Result<(String, Option<PropertyMap>)> {
	Ok((
		String::from("minecraft:chest"),
		Some(Map::from([
			(String::from("facing"), data_facing(data, DIRS_NSWE, 2)?.to_string()),
			(String::from("type"), String::from("single")),
		])),
	))
}

fn convert_log(data: u8) -> (String, Option<PropertyMap>) {
	// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Wood
	let wood = WOOD_VALUES[(data & 0b11) as usize];

	let axis = match data >> 2 {
		0 => "y",
		1 => "x",
		2 => "z",

		// bark
		_ => return (format!("minecraft:{wood}_wood"), None),
	};

	(format!("minecraft:{wood}_log"), Some(Map::from([(String::from("axis"), axis.to_string())])))
}

fn convert_gate(data: u8, name: &str) -> eyre::Result<(String, Option<PropertyMap>)> {
	let facing = data_facing(data, DIRS_SWNE, 0)?;

	let opened = if data & 0b100 != 0 { "opened" } else { "closed" };

	Ok((
		String::from(name),
		Some(Map::from([
			(String::from("facing"), String::from(facing)),
			(String::from("open"), String::from(opened)),
		])),
	))
}

fn convert_stairs(name: &str, data: u8) -> eyre::Result<(String, Option<PropertyMap>)> {
	// https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Stairs

	let facing = data_facing(data, DIRS_EWSN, 0)?;
	let half = if data & 0b100 != 0 { "top" } else { "bottom" };

	Ok((
		name.to_string(),
		Some(Map::from([
			(String::from("facing"), String::from(facing)),
			(String::from("half"), String::from(half)),
		])),
	))
}

fn convert_colourful(name: &str, data: u8) -> (String, Option<PropertyMap>) {
	let colour = COLOURS[(data & 0b1111) as usize];
	(format!("minecraft:{colour}_{name}"), None)
}

/// Converts a [data value](https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values) to a facing direction.
///
/// The `start` parameter specifies the starting index for the facing directions array.
fn data_facing(data: u8, directions: [&str; 4], start: u8) -> eyre::Result<&str> {
	directions.get(((data - start) & 0b11) as usize).copied().ok_or_else(|| {
		eyre!(
			"couldn't determine facing direction: expected data value between {start} and {}, got {data}",
			start + 4
		)
	})
}

#[test]
fn test_data_facing() {
	// beds: https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Beds
	let bed_facings = DIRS_SWNE;
	assert_eq!(data_facing(0, bed_facings, 0).unwrap(), "south");
	assert_eq!(data_facing(1, bed_facings, 0).unwrap(), "west");

	// torches: https://minecraft.wiki/w/Java_Edition_pre-flattening_data_values#Torches_and_Redstone_Torches
	let torch_facings = DIRS_EWSN;
	assert_eq!(data_facing(1, torch_facings, 1).unwrap(), "east");
	assert_eq!(data_facing(3, torch_facings, 1).unwrap(), "south");
}