C++ refactoring + simulation prototype

8 files changed, 790 insertions, 0 deletions

diff --git a/extension/src/openvic2/map/Building.cpp b/extension/src/openvic2/map/Building.cpp
new file mode 100644
index 0000000..f453a0f
--- /dev/null
+++ b/extension/src/openvic2/map/Building.cpp
@@ -0,0 +1,129 @@
+#include "openvic2/map/Building.hpp"
+
+#include <cassert>
+
+#include "openvic2/Logger.hpp"
+
+using namespace OpenVic2;
+
+Building::Building(BuildingType const& new_type) : type{ new_type } {}
+
+bool Building::_can_expand() const {
+	return level < type.get_max_level();
+}
+
+BuildingType const& Building::get_type() const {
+	return type;
+}
+
+Building::level_t Building::get_level() const {
+	return level;
+}
+
+Building::ExpansionState Building::get_expansion_state() const {
+	return expansion_state;
+}
+
+Date const& Building::get_start_date() const {
+	return start;
+}
+
+Date const& Building::get_end_date() const {
+	return end;
+}
+
+float Building::get_expansion_progress() const {
+	return expansion_progress;
+}
+
+return_t Building::expand() {
+	if (expansion_state == ExpansionState::CanExpand) {
+		expansion_state = ExpansionState::Preparing;
+		expansion_progress = 0.0f;
+		return SUCCESS;
+	}
+	return FAILURE;
+}
+
+void Building::update_state(Date const& today) {
+	switch (expansion_state) {
+		case ExpansionState::Preparing:
+			start = today;
+			end = start + type.get_build_time();
+			break;
+		case ExpansionState::Expanding:
+			expansion_progress = static_cast<double>(today - start) / static_cast<double>(end - start);
+			break;
+		default: expansion_state = _can_expand() ? ExpansionState::CanExpand : ExpansionState::CannotExpand;
+	}
+}
+
+void Building::tick(Date const& today) {
+	if (expansion_state == ExpansionState::Preparing) {
+		expansion_state = ExpansionState::Expanding;
+	}
+	if (expansion_state == ExpansionState::Expanding) {
+		if (end <= today) {
+			level++;
+			expansion_state = ExpansionState::CannotExpand;
+		}
+	}
+}
+
+BuildingType::BuildingType(std::string const& new_identifier, Building::level_t new_max_level, Timespan new_build_time) :
+	HasIdentifier{ new_identifier }, max_level{ new_max_level }, build_time{ new_build_time } {
+	assert(new_max_level >= 0);
+	assert(build_time >= 0);
+}
+
+Building::level_t BuildingType::get_max_level() const {
+	return max_level;
+}
+
+Timespan BuildingType::get_build_time() const {
+	return build_time;
+}
+
+return_t BuildingManager::add_building_type(std::string const& identifier, Building::level_t max_level, Timespan build_time) {
+	if (building_types_locked) {
+		Logger::error("The building type list has already been locked!");
+		return FAILURE;
+	}
+	if (identifier.empty()) {
+		Logger::error("Empty building type identifier!");
+		return FAILURE;
+	}
+	if (max_level < 0) {
+		Logger::error("Invalid building type max level: ", max_level);
+		return FAILURE;
+	}
+	if (build_time < 0) {
+		Logger::error("Invalid building type build time: ", build_time);
+		return FAILURE;
+	}
+	BuildingType new_building_type{ identifier, max_level, build_time };
+	BuildingType const* old_building_type = get_building_type_by_identifier(identifier);
+	if (old_building_type != nullptr) {
+		Logger::error("Duplicate building type identifiers: ", old_building_type->get_identifier(), " and ", identifier);
+		return FAILURE;
+	}
+	building_types.push_back(new_building_type);
+	return SUCCESS;
+}
+
+void BuildingManager::lock_building_types() {
+	building_types_locked = true;
+	Logger::info("Locked building types after registering ", building_types.size());
+}
+
+BuildingType const* BuildingManager::get_building_type_by_identifier(std::string const& identifier) const {
+	if (!identifier.empty())
+		for (BuildingType const& building_type : building_types)
+			if (building_type.get_identifier() == identifier) return &building_type;
+	return nullptr;
+}
+
+void BuildingManager::generate_province_buildings(std::vector<Building>& buildings) const {
+	for (BuildingType const& type : building_types)
+		buildings.push_back(Building{ type });
+}
diff --git a/extension/src/openvic2/map/Building.hpp b/extension/src/openvic2/map/Building.hpp
new file mode 100644
index 0000000..7a1a777
--- /dev/null
+++ b/extension/src/openvic2/map/Building.hpp
@@ -0,0 +1,63 @@
+#pragma once
+
+#include <vector>
+
+#include "openvic2/Types.hpp"
+#include "openvic2/Date.hpp"
+
+namespace OpenVic2 {
+	struct BuildingManager;
+	struct BuildingType;
+
+	struct Building {
+		friend struct BuildingManager;
+
+		using level_t = int8_t;
+
+		enum class ExpansionState { CannotExpand, CanExpand, Preparing, Expanding };
+	private:
+		BuildingType const& type;
+		level_t level = 0;
+		ExpansionState expansion_state = ExpansionState::CannotExpand;
+		Date start, end;
+		float expansion_progress;
+
+		Building(BuildingType const& new_type);
+
+		bool _can_expand() const;
+	public:
+		BuildingType const& get_type() const;
+		level_t get_level() const;
+		ExpansionState get_expansion_state() const;
+		Date const& get_start_date() const;
+		Date const& get_end_date() const;
+		float get_expansion_progress() const;
+
+		return_t expand();
+		void update_state(Date const& today);
+		void tick(Date const& today);
+	};
+
+	struct BuildingType : HasIdentifier {
+		friend struct BuildingManager;
+	private:
+		Building::level_t max_level;
+		Timespan build_time;
+
+		BuildingType(std::string const& new_identifier, Building::level_t new_max_level, Timespan new_build_time);
+	public:
+		Building::level_t get_max_level() const;
+		Timespan get_build_time() const;
+	};
+
+	struct BuildingManager {
+	private:
+		std::vector<BuildingType> building_types;
+		bool building_types_locked = false;
+	public:
+		return_t add_building_type(std::string const& identifier, Building::level_t max_level, Timespan build_time);
+		void lock_building_types();
+		BuildingType const* get_building_type_by_identifier(std::string const& identifier) const;
+		void generate_province_buildings(std::vector<Building>& buildings) const;
+	};
+}
diff --git a/extension/src/openvic2/map/Map.cpp b/extension/src/openvic2/map/Map.cpp
new file mode 100644
index 0000000..1089d61
--- /dev/null
+++ b/extension/src/openvic2/map/Map.cpp
@@ -0,0 +1,359 @@
+#include "openvic2/map/Map.hpp"
+
+#include <cassert>
+#include <unordered_set>
+
+#include "openvic2/Logger.hpp"
+
+using namespace OpenVic2;
+
+Mapmode::Mapmode(index_t new_index, std::string const& new_identifier, colour_func_t new_colour_func)
+	: HasIdentifier{ new_identifier }, index{ new_index }, colour_func{ new_colour_func } {
+	assert(colour_func != nullptr);
+}
+
+Mapmode::index_t Mapmode::get_index() const {
+	return index;
+}
+
+Mapmode::colour_func_t Mapmode::get_colour_func() const {
+	return colour_func;
+}
+
+return_t Map::add_province(std::string const& identifier, Province::colour_t colour) {
+	if (provinces_locked) {
+		Logger::error("The map's province list has already been locked!");
+		return FAILURE;
+	}
+	if (provinces.size() >= Province::MAX_INDEX) {
+		Logger::error("The map's province list is full - there can be at most ", Province::MAX_INDEX, " provinces");
+		return FAILURE;
+	}
+	if (identifier.empty()) {
+		Logger::error("Empty province identifier for colour ", Province::colour_to_hex_string(colour));
+		return FAILURE;
+	}
+	if (colour == Province::NULL_COLOUR || colour > Province::MAX_COLOUR) {
+		Logger::error("Invalid province colour: ", Province::colour_to_hex_string(colour));
+		return FAILURE;
+	}
+	Province new_province{ static_cast<Province::index_t>(provinces.size() + 1), identifier, colour };
+	Province const* old_province = get_province_by_identifier(identifier);
+	if (old_province != nullptr) {
+		Logger::error("Duplicate province identifiers: ", old_province->to_string(), " and ", new_province.to_string());
+		return FAILURE;
+	}
+	old_province = get_province_by_colour(colour);
+	if (old_province != nullptr) {
+		Logger::error("Duplicate province colours: ", old_province->to_string(), " and ", new_province.to_string());
+		return FAILURE;
+	}
+	provinces.push_back(new_province);
+	return SUCCESS;
+}
+
+void Map::lock_provinces() {
+	provinces_locked = true;
+	Logger::info("Locked provinces after registering ", provinces.size());
+}
+
+return_t Map::set_water_province(std::string const& identifier) {
+	if (water_provinces_locked) {
+		Logger::error("The map's water provinces have already been locked!");
+		return FAILURE;
+	}
+	Province* province = get_province_by_identifier(identifier);
+	if (province == nullptr) {
+		Logger::error("Unrecognised water province identifier: ", identifier);
+		return FAILURE;
+	}
+	if (province->is_water()) {
+		Logger::error("Province ", identifier, " is already a water province!");
+		return FAILURE;
+	}
+	province->water = true;
+	water_province_count++;
+	return SUCCESS;
+}
+
+void Map::lock_water_provinces() {
+	water_provinces_locked = true;
+	Logger::info("Locked water provinces after registering ", water_province_count);
+}
+
+return_t Map::add_region(std::string const& identifier, std::vector<std::string> const& province_identifiers) {
+	if (regions_locked) {
+		Logger::error("The map's region list has already been locked!");
+		return FAILURE;
+	}
+	if (identifier.empty()) {
+		Logger::error("Empty region identifier!");
+		return FAILURE;
+	}
+	if (provinces.empty()) {
+		Logger::error("Empty province list for region ", identifier);
+		return FAILURE;
+	}
+	return_t ret = SUCCESS;
+	Region new_region{ identifier };
+	for (std::string const& province_identifier : province_identifiers) {
+		Province* province = get_province_by_identifier(province_identifier);
+		if (province != nullptr) {
+			if (new_region.contains_province(province)) {
+				Logger::error("Duplicate province identifier ", province_identifier);
+				ret = FAILURE;
+			} else {
+				size_t other_region_index = reinterpret_cast<size_t>(province->get_region());
+				if (other_region_index != 0) {
+					other_region_index--;
+					if (other_region_index < regions.size())
+						Logger::error("Province ", province_identifier, " is already part of ", regions[other_region_index].get_identifier());
+					else
+						Logger::error("Province ", province_identifier, " is already part of an unknown region with index ", other_region_index);
+					ret = FAILURE;
+				} else new_region.provinces.insert(province);
+			}
+		} else {
+			Logger::error("Invalid province identifier ", province_identifier);
+			ret = FAILURE;
+		}
+	}
+	if (!new_region.get_province_count()) {
+		Logger::error("No valid provinces in region's list");
+		return FAILURE;
+	}
+	Region const* old_region = get_region_by_identifier(identifier);
+	if (old_region != nullptr) {
+		Logger::error("Duplicate region identifiers: ", old_region->get_identifier(), " and ", identifier);
+		return FAILURE;
+	}
+
+	regions.push_back(new_region);
+	// Used to detect provinces listed in multiple regions, will
+	// be corrected once regions is stable (i.e. lock_regions).
+	Region* tmp_region_index = reinterpret_cast<Region*>(regions.size());
+	for (Province* province : new_region.get_provinces())
+		province->region = tmp_region_index;
+	return ret;
+}
+
+void Map::lock_regions() {
+	regions_locked = true;
+	for (Region& region : regions)
+		for (Province* province : region.get_provinces())
+			province->region = &region;
+	Logger::info("Locked regions after registering ", regions.size());
+}
+
+size_t Map::get_province_count() const {
+	return provinces.size();
+}
+
+Province* Map::get_province_by_index(Province::index_t index) {
+	return index != Province::NULL_INDEX && index <= provinces.size() ? &provinces[index - 1] : nullptr;
+}
+
+Province const* Map::get_province_by_index(Province::index_t index) const {
+	return index != Province::NULL_INDEX && index <= provinces.size() ? &provinces[index - 1] : nullptr;
+}
+
+Province* Map::get_province_by_identifier(std::string const& identifier) {
+	if (!identifier.empty())
+		for (Province& province : provinces)
+			if (province.get_identifier() == identifier) return &province;
+	return nullptr;
+}
+
+Province const* Map::get_province_by_identifier(std::string const& identifier) const {
+	if (!identifier.empty())
+		for (Province const& province : provinces)
+			if (province.get_identifier() == identifier) return &province;
+	return nullptr;
+}
+
+Province* Map::get_province_by_colour(Province::colour_t colour) {
+	if (colour != Province::NULL_COLOUR)
+		for (Province& province : provinces)
+			if (province.get_colour() == colour) return &province;
+	return nullptr;
+}
+
+Province const* Map::get_province_by_colour(Province::colour_t colour) const {
+	if (colour != Province::NULL_COLOUR)
+		for (Province const& province : provinces)
+			if (province.get_colour() == colour) return &province;
+	return nullptr;
+}
+
+Province::index_t Map::get_province_index_at(size_t x, size_t y) const {
+	if (x < width && y < height) return province_index_image[x + y * width];
+	return Province::NULL_INDEX;
+}
+
+Region* Map::get_region_by_identifier(std::string const& identifier) {
+	if (!identifier.empty())
+		for (Region& region : regions)
+			if (region.get_identifier() == identifier) return &region;
+	return nullptr;
+}
+
+Region const* Map::get_region_by_identifier(std::string const& identifier) const {
+	if (!identifier.empty())
+		for (Region const& region : regions)
+			if (region.get_identifier() == identifier) return &region;
+	return nullptr;
+}
+
+static Province::colour_t colour_at(uint8_t const* colour_data, int32_t idx) {
+	return (colour_data[idx * 3] << 16) | (colour_data[idx * 3 + 1] << 8) | colour_data[idx * 3 + 2];
+}
+
+return_t Map::generate_province_index_image(size_t new_width, size_t new_height, uint8_t const* colour_data) {
+	if (!province_index_image.empty()) {
+		Logger::error("Province index image has already been generated!");
+		return FAILURE;
+	}
+	if (!provinces_locked) {
+		Logger::error("Province index image cannot be generated until after provinces are locked!");
+		return FAILURE;
+	}
+	if (new_width < 1 || new_height < 1) {
+		Logger::error("Invalid province image dimensions: ", new_width, "x", new_height);
+		return FAILURE;
+	}
+	if (colour_data == nullptr) {
+		Logger::error("Province colour data pointer is null!");
+		return FAILURE;
+	}
+	width = new_width;
+	height = new_height;
+	province_index_image.resize(width * height);
+
+	std::vector<bool> province_checklist(provinces.size());
+	return_t ret = SUCCESS;
+	std::unordered_set<Province::colour_t> unrecognised_colours;
+
+	for (int32_t y = 0; y < height; ++y) {
+		for (int32_t x = 0; x < width; ++x) {
+			const int32_t idx = x + y * width;
+			const Province::colour_t colour = colour_at(colour_data, idx);
+			if (x > 0) {
+				const int32_t jdx = idx - 1;
+				if (colour_at(colour_data, jdx) == colour) {
+					province_index_image[idx] = province_index_image[jdx];
+					continue;
+				}
+			}
+			if (y > 0) {
+				const int32_t jdx = idx - width;
+				if (colour_at(colour_data, jdx) == colour) {
+					province_index_image[idx] = province_index_image[jdx];
+					continue;
+				}
+			}
+			Province const* province = get_province_by_colour(colour);
+			if (province != nullptr) {
+				const Province::index_t index = province->get_index();
+				province_index_image[idx] = index;
+				province_checklist[index - 1] = true;
+				continue;
+			}
+			if (unrecognised_colours.find(colour) == unrecognised_colours.end()) {
+				unrecognised_colours.insert(colour);
+				Logger::error("Unrecognised province colour ", Province::colour_to_hex_string(colour), " at (", x, ", ", y, ")");
+				ret = FAILURE;
+			}
+			province_index_image[idx] = Province::NULL_INDEX;
+		}
+	}
+
+	for (size_t idx = 0; idx < province_checklist.size(); ++idx) {
+		if (!province_checklist[idx]) {
+			Logger::error("Province missing from shape image: ", provinces[idx].to_string());
+			ret = FAILURE;
+		}
+	}
+	return ret;
+}
+
+size_t Map::get_width() const {
+	return width;
+}
+
+size_t Map::get_height() const {
+	return height;
+}
+
+std::vector<Province::index_t> const& Map::get_province_index_image() const {
+	return province_index_image;
+}
+
+return_t Map::add_mapmode(std::string const& identifier, Mapmode::colour_func_t colour_func) {
+	if (identifier.empty()) {
+		Logger::error("Empty mapmode identifier!");
+		return FAILURE;
+	}
+	if (colour_func == nullptr) {
+		Logger::error("Mapmode colour function is null for identifier: ", identifier);
+		return FAILURE;
+	}
+	Mapmode new_mapmode{ mapmodes.size(), identifier, colour_func };
+	Mapmode const* old_mapmode = get_mapmode_by_identifier(identifier);
+	if (old_mapmode != nullptr) {
+		Logger::error("Duplicate mapmode identifiers: ", old_mapmode->get_identifier(), " and ", identifier);
+		return FAILURE;
+	}
+	mapmodes.push_back(new_mapmode);
+	return SUCCESS;
+}
+
+size_t Map::get_mapmode_count() const {
+	return mapmodes.size();
+}
+
+Mapmode const* Map::get_mapmode_by_index(size_t index) const {
+	return index < mapmodes.size() ? &mapmodes[index] : nullptr;
+}
+
+Mapmode const* Map::get_mapmode_by_identifier(std::string const& identifier) const {
+	if (!identifier.empty())
+		for (Mapmode const& mapmode : mapmodes)
+			if (mapmode.get_identifier() == identifier) return &mapmode;
+	return nullptr;
+}
+
+return_t Map::generate_mapmode_colours(Mapmode::index_t index, uint8_t* target) const {
+	if (target == nullptr) {
+		Logger::error("Mapmode colour target pointer is null!");
+		return FAILURE;
+	}
+	if (index >= mapmodes.size()) {
+		Logger::error("Invalid mapmode index: ", index);
+		return FAILURE;
+	}
+	Mapmode const& mapmode = mapmodes[index];
+	target += 4; // Skip past Province::NULL_INDEX
+	for (Province const& province : provinces) {
+		const Province::colour_t colour = mapmode.get_colour_func()(*this, province);
+		*target++ = (colour >> 16) & 0xFF;
+		*target++ = (colour >> 8) & 0xFF;
+		*target++ = colour & 0xFF;
+		*target++ = province.is_water() ? 0 : 255;
+	}
+	return SUCCESS;
+}
+
+void Map::generate_province_buildings(BuildingManager const& manager) {
+	for (Province& province : provinces)
+		manager.generate_province_buildings(province.buildings);
+}
+
+void Map::update_state(Date const& today) {
+	for (Province& province : provinces)
+		province.update_state(today);
+}
+
+void Map::tick(Date const& today) {
+	for (Province& province : provinces)
+		province.tick(today);
+}
diff --git a/extension/src/openvic2/map/Map.hpp b/extension/src/openvic2/map/Map.hpp
new file mode 100644
index 0000000..b6e7ac2
--- /dev/null
+++ b/extension/src/openvic2/map/Map.hpp
@@ -0,0 +1,73 @@
+#pragma once
+
+#include <functional>
+
+#include "openvic2/map/Region.hpp"
+
+namespace OpenVic2 {
+
+	struct Mapmode : HasIdentifier {
+		friend struct Map;
+
+		using colour_func_t = std::function<Province::colour_t (Map const&, Province const&)>;
+		using index_t = size_t;
+	private:
+		index_t index;
+		colour_func_t colour_func;
+
+		Mapmode(index_t new_index, std::string const& new_identifier, colour_func_t new_colour_func);
+	public:
+		index_t get_index() const;
+		colour_func_t get_colour_func() const;
+	};
+
+	/* REQUIREMENTS:
+	 * MAP-4
+	 */
+	struct Map {
+	private:
+		std::vector<Province> provinces;
+		std::vector<Region> regions;
+		bool provinces_locked = false, water_provinces_locked = false, regions_locked = false;
+		size_t water_province_count = 0;
+
+		size_t width = 0, height = 0;
+		std::vector<Province::index_t> province_index_image;
+		std::vector<Mapmode> mapmodes;
+	public:
+		return_t add_province(std::string const& identifier, Province::colour_t colour);
+		void lock_provinces();
+		return_t set_water_province(std::string const& identifier);
+		void lock_water_provinces();
+		return_t add_region(std::string const& identifier, std::vector<std::string> const& province_identifiers);
+		void lock_regions();
+
+		size_t get_province_count() const;
+		Province* get_province_by_index(Province::index_t index);
+		Province const* get_province_by_index(Province::index_t index) const;
+		Province* get_province_by_identifier(std::string const& identifier);
+		Province const* get_province_by_identifier(std::string const& identifier) const;
+		Province* get_province_by_colour(Province::colour_t colour);
+		Province const* get_province_by_colour(Province::colour_t colour) const;
+		Province::index_t get_province_index_at(size_t x, size_t y) const;
+
+		Region* get_region_by_identifier(std::string const& identifier);
+		Region const* get_region_by_identifier(std::string const& identifier) const;
+
+		return_t generate_province_index_image(size_t new_width, size_t new_height, uint8_t const* colour_data);
+		size_t get_width() const;
+		size_t get_height() const;
+		std::vector<Province::index_t> const& get_province_index_image() const;
+
+		return_t add_mapmode(std::string const& identifier, Mapmode::colour_func_t colour_func);
+		size_t get_mapmode_count() const;
+		Mapmode const* get_mapmode_by_index(Mapmode::index_t index) const;
+		Mapmode const* get_mapmode_by_identifier(std::string const& identifier) const;
+		return_t generate_mapmode_colours(Mapmode::index_t index, uint8_t* target) const;
+
+		void generate_province_buildings(BuildingManager const& manager);
+
+		void update_state(Date const& today);
+		void tick(Date const& today);
+	};
+}
diff --git a/extension/src/openvic2/map/Province.cpp b/extension/src/openvic2/map/Province.cpp
new file mode 100644
index 0000000..c641b7e
--- /dev/null
+++ b/extension/src/openvic2/map/Province.cpp
@@ -0,0 +1,67 @@
+#include "openvic2/map/Province.hpp"
+
+#include <cassert>
+#include <sstream>
+#include <iomanip>
+
+using namespace OpenVic2;
+
+Province::Province(index_t new_index, std::string const& new_identifier, colour_t new_colour) :
+	HasIdentifier{ new_identifier }, index{ new_index }, colour{ new_colour } {
+	assert(index != NULL_INDEX);
+	assert(colour != NULL_COLOUR);
+}
+
+std::string Province::colour_to_hex_string(colour_t colour) {
+	std::ostringstream stream;
+	stream << std::hex << std::setfill('0') << std::setw(6) << colour;
+	return stream.str();
+}
+
+Province::index_t Province::get_index() const {
+	return index;
+}
+
+Province::colour_t Province::get_colour() const {
+	return colour;
+}
+
+Region* Province::get_region() const {
+	return region;
+}
+
+bool Province::is_water() const {
+	return water;
+}
+
+Province::life_rating_t Province::get_life_rating() const {
+	return life_rating;
+}
+
+std::vector<Building> const& Province::get_buildings() const {
+	return buildings;
+}
+
+return_t Province::expand_building(std::string const& building_type_identifier) {
+	for (Building& building : buildings)
+		if (building.get_type().get_identifier() == building_type_identifier)
+			return building.expand();
+	return FAILURE;
+}
+
+std::string Province::to_string() const {
+	std::stringstream stream;
+	stream << "(#" << std::to_string(index) << ", " << get_identifier() << ", 0x" << colour_to_hex_string(colour) << ")";
+	return stream.str();
+}
+
+void Province::update_state(Date const& today) {
+	for (Building& building : buildings)
+		building.update_state(today);
+
+}
+
+void Province::tick(Date const& today) {
+	for (Building& building : buildings)
+		building.tick(today);
+}
diff --git a/extension/src/openvic2/map/Province.hpp b/extension/src/openvic2/map/Province.hpp
new file mode 100644
index 0000000..79c6861
--- /dev/null
+++ b/extension/src/openvic2/map/Province.hpp
@@ -0,0 +1,45 @@
+#pragma once
+
+#include "openvic2/map/Building.hpp"
+
+namespace OpenVic2 {
+	struct Map;
+	struct Region;
+
+	/* REQUIREMENTS:
+	 * MAP-5, MAP-8, MAP-43, MAP-47
+	 */
+	struct Province : HasIdentifier {
+		friend struct Map;
+
+		using colour_t = uint32_t;
+		using index_t = uint16_t;
+		using life_rating_t = int8_t;
+
+		static constexpr colour_t NULL_COLOUR = 0, MAX_COLOUR = 0xFFFFFF;
+		static constexpr index_t NULL_INDEX = 0, MAX_INDEX = 0xFFFF;
+	private:
+		index_t index;
+		colour_t colour;
+		Region* region = nullptr;
+		bool water = false;
+		life_rating_t life_rating = 0;
+		std::vector<Building> buildings;
+
+		Province(index_t new_index, std::string const& new_identifier, colour_t new_colour);
+	public:
+		static std::string colour_to_hex_string(colour_t colour);
+
+		index_t get_index() const;
+		colour_t get_colour() const;
+		Region* get_region() const;
+		bool is_water() const;
+		life_rating_t get_life_rating() const;
+		std::vector<Building> const& get_buildings() const;
+		return_t expand_building(std::string const& building_type_identifier);
+		std::string to_string() const;
+
+		void update_state(Date const& today);
+		void tick(Date const& today);
+	};
+}
diff --git a/extension/src/openvic2/map/Region.cpp b/extension/src/openvic2/map/Region.cpp
new file mode 100644
index 0000000..3e5bee7
--- /dev/null
+++ b/extension/src/openvic2/map/Region.cpp
@@ -0,0 +1,26 @@
+#include "openvic2/map/Region.hpp"
+
+#include <cassert>
+#include <algorithm>
+
+using namespace OpenVic2;
+
+size_t ProvinceSet::get_province_count() const {
+	return provinces.size();
+}
+
+bool ProvinceSet::contains_province(Province const* province) const {
+	return province && std::find(provinces.begin(), provinces.end(), province) != provinces.end();
+}
+
+std::set<Province*> const& ProvinceSet::get_provinces() const {
+	return provinces;
+}
+
+Region::Region(std::string const& new_identifier) : HasIdentifier{ new_identifier } {}
+
+Province::colour_t Region::get_colour() const {
+	if (provinces.empty()) return 0xFF0000;
+	Province const* province = *provinces.cbegin();
+	return province->get_colour();
+}
diff --git a/extension/src/openvic2/map/Region.hpp b/extension/src/openvic2/map/Region.hpp
new file mode 100644
index 0000000..2eec1cd
--- /dev/null
+++ b/extension/src/openvic2/map/Region.hpp
@@ -0,0 +1,28 @@
+#pragma once
+
+#include <set>
+
+#include "openvic2/map/Province.hpp"
+
+namespace OpenVic2 {
+
+	struct ProvinceSet {
+	protected:
+		std::set<Province*> provinces;
+	public:
+		size_t get_province_count() const;
+		bool contains_province(Province const* province) const;
+		std::set<Province*> const& get_provinces() const;
+	};
+
+	/* REQUIREMENTS:
+	 * MAP-6, MAP-44, MAP-48
+	 */
+	struct Region : HasIdentifier, ProvinceSet {
+		friend struct Map;
+	private:
+		Region(std::string const& new_identifier);
+	public:
+		Province::colour_t get_colour() const;
+	};
+}