Module:BuildingData

Documentation for this module may be created at Module:BuildingData/doc

-------------------------------------------------------------------------------
-- This module primarily supplies data and lookup functions for other modules 
-- that support templates like {{Building_link}}.
-- https://hoodedhorse.com/wiki/Against_the_Storm/Template:Building_link
-- 
-- The main data table stores all available data about buildings themselves 
-- and relies on other modules to store relationships between buildings and 
-- products, services, etc.
--
-- The helper functions include getters (to keep the data hidden) and a large
-- deconfliction method to provide some robustness when using the template
-- and from other Lua modules. Looking up a building requires using in-game 
-- names, but forgives small differences in spacing, apostrophes, and plurals.

-- Please help keep this table updated as the game is updated.
-- @module BuildingData
local BuildingData = {}

--
-- Dependencies
--
RecipeData = RecipeData or require("Module:RecipeData") -- need recipe relationships
Utility = Utility or require("Module:Utility") -- need normalize functions



-- 
-- Constants
-- 
-- Specializations
local S_ALCH = "Alchemy"
local S_BREW = "Brewing"
local S_CLOT = "Cloth"
local S_ENGI = "Engineering"
local S_MEAT = "Meat production"
local S_WARM = "Warmth"
local S_WOOD = "Wood"

-- Resource names of building costs
local C_BRICK = "Bricks"
local C_FABRI = "Fabric"
local C_PARTS = "Parts"
local C_PIPES = "Pipes"
local C_PLANK = "Planks"

-- Rain types for rain engines
local R_DRIZZ = "Drizzle Water"
local R_CLEAR = "Clearance Water"
local R_STORM = "Storm Water"



--
-- Class Variables
--

-------------------------------------------------------------------------------
-- Primary data table for this module.
-- 
-- This table stores the details of buildings according to in-game information.
-- A design decision of this table is to make the key the same as the page 
-- name, so that whenever .page is referenced, it can be used again to retrieve 
-- the rest of the data. (The lookup method will handle converting it to 
-- lowercase.)
--
-- Structure:
-- @key a lowercase version of the building name, with the same spaces, 
-- apostrophes, singular, and spelling
-- @field page the name of the wiki page, case-sensitive, but otherwise must be 
-- the same as the key
-- @field iconfile a string of the filename.png of the icon used in the game, 
-- case-sensitive and must include extension, but without the "File:"
-- @field specialization[opt] a table of the specializations listed in the 
-- in-game encyclopedia (use the constants, above), or omit if none
-- @field cost[opt] a table of the building costs (or omit if none), in the 
-- following format:
-- 		{ first cost { number, resource },
--		  second cost { number, resource },
--		  etc. }
-- @field workers the number of worker slots
-- @field raintype the color of rain used in the Rain Engine of this building 
-- (use constants, above), if any
-- @field description the in-game description text, in plain text
-- @table tBuildingData the primary data table for buildings
local tBuildingData = { 
	
	-- Starting Buildings
	["ancient hearth"] = { page="Ancient Hearth", 
		iconfile="Small Hearth icon.png", 
		specialization={ S_WARM }, 
		workers=1, 
		description="The heart of the colony is protected by the Holy Flame. Villagers gather here to rest, eat, and receive clothing. If the fire goes out, people will lose hope. Can't be moved. Size: 4x4." },
	["main warehouse"] = { page="Main Warehouse", 
		iconfile="Main_Storage_icon.png" },
	
	-- Camps
	["foragers' camp"] = { page="Foragers' Camp", 
		iconfile="Forager's Camp icon" },
	["harvesters' camp"] = { page="Harvesters' Camp", 
		iconfile="Harvester Camp icon.png" },
	["herbalists' camp"] = { page="Herbalists' Camp", 
		iconfile="Herbalist's_Camp_icon.png" },
	["stonecutters' camp"] = { page="Stonecutters' Camp", 
		iconfile="Stonecutter's Camp icon.png" },
	["trappers' camp"] = { page="Trappers' Camp", 
		iconfile="Trapper's Camp icon.png" },
	["woodcutters' camp"] = { page="Woodcutters' Camp", 
		iconfile="Woodcutters Camp icon" },
	
	-- Farms
	["farm field"] = { page="Farm Field", 
		iconfile="Farmfield_icon.png" },
	["greenhouse"] = { page="Greenhouse", 
		iconfile="Greenhouse_icon.png" },
	["herb garden"] = { page="Herb Garden", 
		iconfile="HerbGarden_icon.png" },
	["plantation"] = { page="Plantation", 
		iconfile="Plantation_icon.png" },
	["small farm"] = { page="Small Farm", 
		iconfile="SmallFarm_icon.png" },
	
	-- Food production
	["bakery"] = { page="Bakery", 
		iconfile="Bakery_icon.png" },
	["butcher"] = { page="Butcher", 
		iconfile="Butcher_icon.png" },
	["cellar"] = { page="Cellar", 
		iconfile="Cellar_icon.png" },
	["cookhouse"] = { page="Cookhouse", 
		iconfile="Cookhouse_icon.png" },
	["field kitchen"] = { page="Field Kitchen", 
		iconfile="Field_Kitchen_icon.png" },
	["granary"] = { page="Granary", 
		iconfile="Granary_icon.png" },
	["grill"] = { page="Grill", 
		iconfile="Grill_icon.png" },
	["ranch"] = { page="Ranch", 
		iconfile="Ranch_icon.png" },
	["smokehouse"] = { page="Smokehouse", 
		iconfile="Smokehouse_icon.png" },
	
	-- Housing
	["shelter"] = { page="Shelter", 
		iconfile="Shelter icon.png" },
	["big shelter"] = { page="Big Shelter", 
		iconfile="Big Shelter icon.png" },
	["human house"] = { page="Human House", 
		iconfile="Human House icon.png" },
	["beaver house"] = { page="Beaver House", 
		iconfile="Beaver House icon.png" },
	["lizard house"] = { page="Lizard House", 
		iconfile="Lizard House icon.png" },
	["harpy house"] = { page="Harpy House", 
		iconfile="Harpy House icon.png" },
	
	-- Industry
	["crude workstation"] = { page="Crude Workstation", 
		iconfile="Crude_Workstation_icon.png" },
	["makeshift post"] = { page="Makeshift Post", 
		iconfile="Makeshift_Post_icon.png" },
	["advanced rain collector"] = { page="Advanced Rain Collector", 
		iconfile="Advanced_Rain_Collector_icon.png", 
		specialization={ S_ENGI, S_ALCH }, 
		cost={ {5,C_PIPES}, {3,C_PARTS}, {5,C_PLANK} }, 
		description="Can collect infused rainwater used for crafting and powering Rain Engines in production buildings. The type of collected rainwater depends on the season. Can't be moved. Size: 3x2." },
	["alchemist's hut"] = { page="Alchemist's Hut", 
		iconfile="Alchemist_Hut_icon.png",
		specialization={ S_ALCH, S_BREW }, 
		cost={ {5,C_PLANK}, {2,C_BRICK} }, 
		workers=2, 
		raintype=R_CLEAR, 
		description="Can produce: Crystalized Dew (★★), Cosmetics (★★), Wine (★★). Can use: Clearance Water. Can't be moved. Size: 3x2." },
	["apothecary"] = { page="Apothecary", 
		iconfile="Apothecary_icon.png", 
		specialization={ S_ALCH }, 
		cost={ {5,C_PLANK}, {2,C_BRICK} }, 
		workers=2, 
		raintype=R_CLEAR, 
		description="Can produce: Cosmetics (★★), Incense (★★), Biscuits (★★). Can use: Clearance Water. Can't be moved. Size: 3x3." },
	["artisan"] = { page="Artisan", 
		iconfile="Artisan_icon.png" },
	["brewery"] = { page="Brewery", 
		iconfile="Brewery_icon.png" },
	["brick oven"] = { page="Brick Oven", 
		iconfile="Brick_Oven_icon.png" },
	["brickyard"] = { page="Brickyard", 
		iconfile="Brickyard_icon.png" },
	["carpenter"] = { page="Carpenter", 
		iconfile="Carpenter_icon.png" },
	["clothier"] = { page="Clothier", 
		iconfile="Clothier_icon.png" },
	["cooperage"] = { page="Cooperage", 
		iconfile="Cooperage_icon.png" },
	["druid's hut"] = { page="Druid's Hut", 
		iconfile="Druid_icon.png" },
	["flawless brewery"] = { page="Flawless Brewery", 
		iconfile="Brewery_icon.png" },
	["flawless rain mill"] = { page="Flawless Rain Mill", 
		iconfile="Rain_Mill_icon.png" },
	["furnace"] = { page="Furnace", 
		iconfile="Furnace_icon.png" },
	["kiln"] = { page="Kiln", 
		iconfile="Kiln_icon.png" },
	["leatherworker"] = { page="Leatherworker", 
		iconfile="Leatherworks_icon.png" },
	["lumber mill"] = { page="Lumber Mill", 
		iconfile="Lumbermill_icon.png" },
	["mine"] = { page="Mine", 
		iconfile="Mine_icon.png" },
	["press"] = { page="Press", 
		iconfile="Press_icon.png" },
	["provisioner"] = { page="Provisioner", 
		iconfile="Provisioner_icon.png" },
	["rain collector"] = { page="Rain Collector", 
		iconfile="Rain_Collector_icon.png" },
	["rain mill"] = { page="Rain Mill", 
		iconfile="Rain_Mill_icon.png" },
	["scribe"] = { page="Scribe", 
		iconfile="Scribe_icon.png" },
	["smelter"] = { page="Smelter", 
		iconfile="Smelter_icon.png" },
	["toolshop"] = { page="Toolshop", 
		iconfile="Toolshop_icon.png" },
	["weaver"] = { page="Weaver", 
		iconfile="Weaver_icon.png" },
	
	-- City Buildings
	["archaeologist's office"] = { page="Archaeologist's Office", 
		iconfile="Archeologist_office_icon.png",
		cost={ {2,C_PLANK}, {2,C_BRICK}, {2,C_FABRI} }, 
		description="A building designed to help you study the past. Can be upgraded to locate archaeological discoveries or improve exploration capabilities. Can be moved for: 5 Wood. Size: 3x3." },
	["small hearth"] = { page="Small Hearth", 
		iconfile="Temporary_Hearth_icon.png" },
	["warehouse"] = { page="Warehouse", 
		iconfile="Storage_icon.png" },
	["trading post"] = { page="Trading Post", 
		iconfile="Trading_Post_icon.png" },
	["blight post"] = { page="Blight Post", 
		iconfile="Blight_Post_icon.png" },
	["hydrant"] = { page="Hydrant", 
		iconfile="Hydrant_icon.png" },
	["forsaken altar"] = { page="Forsaken Altar", 
		iconfile="Altar_icon.png" },
	
	-- Service Buildings
	["bath house"] = { page="Bath House", 
		iconfile="Bath_House_icon.png" },
	["clan hall"] = { page="Clan Hall", 
		iconfile="Clan_Hall_icon.png" },
	["explorers' lodge"] = { page="Explorers' Lodge", 
		iconfile="Explorers_Lodge_icon.png" },
	["guild house"] = { page="Guild House",	
		iconfile="Guild_House_icon.png"	},
	["monastery"] = { page="Monastery", 
		iconfile="Monastery_icon.png"},
	["tavern"] = { page="Tavern", 
		iconfile="Tavern_icon.png" },
	["temple"] = { page="Temple", 
		iconfile="Temple_icon.png" },
		
} -- end of tBuildingData



-------------------------------------------------------------------------------
-- Main lookup function
-- 
-- Accepts the in-game name and returns the corresponding inner table from
-- tBuildingData. It is preferred that callers use the other getter functions
-- that return specific fields of the inner table rather than the whole thing,
-- to protect variations in this module.
-- @param buildingName the name of the building to look up
-- @return the inner table from the big data table corresponding to the provided
-- building name, or nil if it doesn't exist
function BuildingData.getData(buildingName)
	
	-- If the argument to this function is empty or nil, save some time by 
	-- skipping the normalize function.
	if not buildingName or "" == buildingName then
		return nil
	end
	
	-- normalize the name to try again
    local buildingName = Utility.normalizeBuildingName(buildingName)
	
	-- get the inner table from the big data table and return it; if it doesn't
	-- exist, this will return nil anyway
    return tBuildingData[buildingName] or nil
end



---
-- Getter method for the page name for a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding name
-- of the page in the wiki for the building. If the buildingName argument is 
-- formatted exactly as in the game, this will return a string matching the
-- argument. Since normalization is performed, this can be used to ensure proper
-- formatting of the building's name.
-- @param buildingName the name of the building
-- @return the name of the page on the wiki, or nil if it doens't exist
function BuildingData.getPagename(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	if not tBuilding then
		return nil
	end
	
	-- if the building didn't exist, then nil was already returned, but if the
	-- page was undefined, this should return nil instead of an empty string
	return tBuilding.page
end



---
-- Getter method for the icon filename for a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- filename on the wiki for the building's icon as seen in-game.
-- @param buildingName the name of the building
-- @return the filename, which might be an empty string, or nil if it doesn't 
-- exist
function BuildingData.getIconFilename(buildingName)
	
	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	if not tBuilding then
		return nil
	end
	
	-- Get the icon filename, if any. If the building doesn't have an icon,
	-- then return an empty string. Returning nil is reserved for when the 
	-- building does not exist.
	return tBuilding.iconfile or ""
end



---
-- Getter method for the specializations of a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- specializations, if any, as a table of strings.
-- @param the name of the building
-- @return a table with the specializations for the building, which might be
-- empty if the building has no specializations, or nil if the building doesn't 
-- exist
function BuildingData.getSpecialization(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	
	-- if the building didn't exist, return nil
	if not tBuilding then
		return nil
	end
	
	local tSpec = {} -- this is our return variable
	
	-- Get the specialization, if any. If there are none, then return that empty 
	-- table. Returning nil is reserved for when the building does not exist.
	if tBuilding.specialization then
		-- overwrite the return variable
		tSpec = tBuilding.specialization
	end
	
	-- At this point, it could be an empty table, signifying that the building
	-- exists but has no specialization.
	return tSpec
end



---
-- Getter method for the building costs of a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- costs in resources to build as a table of strings. Buildings that the player
-- starts with or are otherwise free to build will have no costs.
-- @param the name of the building
-- @return a table with the costs of the building, which may be empty if the 
-- player starts with the building, or nil if the building doesn't exist; the
-- cost table has the following format:
-- 		{ first cost { number, resource },
--		  second cost { number, resource },
--		  etc. }
function BuildingData.getCosts(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	
	-- if the building didn't exist, return nil
	if not tBuilding then
		return nil
	end
	
	local tCost = {} -- this is our return variable
	
	-- Get the costs, if any. If there are none, then return that empty table. 
	-- Returning nil is reserved for when the building does not exist.
	if tBuilding.cost then
		-- overwrite the return variable
		tCost = tBuilding.cost
	end
	
	-- At this point, it could be an empty table, signifying that the building
	-- exists but has no cost.
	return tCost
end



---
-- Getter method for the number of worker slots at a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- number of workers the building can take, if any.
-- @param the name of the building
-- @return the number of workers, which might be zero, or nil if the building 
-- doesn't exist
function BuildingData.getWorkers(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	if not tBuilding then
		return nil
	end
	
	-- Get the number of worker slots, if any. If there are none, then return 
	-- zero. Returning nil is reserved for when the building does not exist.
	return tBuilding.workers or 0
end



---
-- Getter method for the type of rain used in Rain Engines in a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- rain type.
-- @param the name of the building
-- @return the rain type, if any, or nil if the building doesn't exist
function BuildingData.getRainType(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	if not tBuilding then
		return nil
	end
	
	-- Get the rain type, if any. If the building cannot have rain engines, then 
	-- return an empty string. Returning nil is reserved for when the building 
	-- does not exist.
	return tBuilding.raintype or ""
end



---
-- Getter method for the description for a building.
-- 
-- Accepts the in-game name of the building and returns the corresponding 
-- description text, as seen in the game.
-- @param buildingName the name of the building
-- @return the description of the building, which might be an empty string, or 
-- nil if it doesn't exist
function BuildingData.getDescription(buildingName)

	-- get the inner table for the building
	local tBuilding = BuildingData.getData(buildingName)
	if not tBuilding then
		return nil
	end
	
	-- Get the description, if any. If the building doesn't have a description,
	-- then return an empty string. Returning nil is reserved for when the 
	-- building does not exist.
	return tBuilding.description or ""	
end



-- Return this class when required into another module.
return BuildingData