From 704db1517d6231d7206f8d009a9b60019bde8914 Mon Sep 17 00:00:00 2001 From: Vanic Date: Sat, 30 Aug 2025 14:12:19 +0000 Subject: [PATCH] MapGen: rewrite & add annotations --- mods/CORE/MapGen/src/MapGen.lua | 119 +++++++++++++----- mods/CORE/MapGen/src/MapGen/Layer.lua | 58 ++++++--- mods/CORE/MapGen/src/MapGen/Region.lua | 15 ++- .../MapGen/src/MapGen/Region/Region2D.lua | 14 ++- .../MapGen/src/MapGen/Region/Region3D.lua | 16 ++- mods/CORE/MapGen/src/MapGen/Utils.lua | 41 +++--- 6 files changed, 186 insertions(+), 77 deletions(-) diff --git a/mods/CORE/MapGen/src/MapGen.lua b/mods/CORE/MapGen/src/MapGen.lua index 2ce6c76..68b7ffe 100644 --- a/mods/CORE/MapGen/src/MapGen.lua +++ b/mods/CORE/MapGen/src/MapGen.lua @@ -1,19 +1,40 @@ -local modInfo = Mod.getInfo() -local require = modInfo.require -local MapGenUtils = require("MapGen.Utils") -local Layer = require("MapGen.Layer") -local Region2D = require("MapGen.Region.Region2D") -local Region3D = require("MapGen.Region.Region3D") - local core, table, math = core, table, math local ipairs = pairs, ipairs --- Main MapGen class -local MapGen = {} -MapGen.__index = MapGen +local modInfo = Mod.getInfo() +local require = modInfo.require +---@type MapGen.Utils +local MapGenUtils = require("MapGen.Utils") + +---@type MapGen.Layer +local Layer = require("MapGen.Layer") + +---@type MapGen.Region.Region2D +local Region2D = require("MapGen.Region.Region2D") + +---@type MapGen.Region.Region3D +local Region3D = require("MapGen.Region.Region3D") + +---@class MapGen +---@field layersByName table +---@field layersList table +---@field registeredRegions table +---@field material table +local MapGen = { + layersByName = nil, + layersList = nil, + registeredRegions = nil, + materials = { + impassableWater = nil, + impassableSeabed = nil, + air = nil, + }, +} + +---@return MapGen function MapGen:new() - return setmetatable({ + local instance = setmetatable({ layersByName = {}, layersList = {}, registeredRegions = {}, @@ -21,29 +42,58 @@ function MapGen:new() impassableWater = core.get_content_id("impassable_water:water"), impassableSeabed = core.get_content_id("impassable_water:seabed"), air = core.get_content_id("air") - } - }, self) + }, + }, {__index = self}) + + return instance end +---@param name string +---@param minY number +---@param maxY number +---@return MapGen.Layer function MapGen:registerLayer(name, minY, maxY) + ---@type MapGen.Layer local layer = Layer:new(name, minY, maxY) + self.layersByName[name] = layer table.insert(self.layersList, layer) + return layer end +---@param params table function MapGen:register2DRegion(params) + ---@type MapGen.Region.Region2D local region = Region2D:new(params) + + ---@type MapGen.Layer local layer = self.layersByName[params.layerName] - if not layer then error("Invalid layer: " .. params.layerName) end + + if not layer then + error("Invalid layer: " .. params.layerName) + end + layer:add2DRegion(region) + + -- TODO: тут не надо возвращать регион? end +---@param params table function MapGen:register3DRegion(params) + ---@type MapGen.Region.Region3D local region = Region3D:new(params) + + ---@type MapGen.Layer local layer = self.layersByName[params.layerName] - if not layer then error("Invalid layer: " .. params.layerName) end + + if not layer then + error("Invalid layer: " .. params.layerName) + end + layer:add3DRegion(region) + + -- TODO: тут не надо возвращать регион? end function MapGen:enable() @@ -52,7 +102,10 @@ function MapGen:enable() end) end --- Main generation logic +--- Main generation logic +---@param minp table TODO: заменить тип на класс/вектор координат +---@param maxp table TODO: заменить тип на класс/вектор координат +---@param seed number function MapGen:onMapGenerated(minp, maxp, seed) local vm, emin, emax = core.get_mapgen_object("voxelmanip") local area = VoxelArea:new{MinEdge=emin, MaxEdge=emax} @@ -71,11 +124,14 @@ function MapGen:onMapGenerated(minp, maxp, seed) vm:write_to_map() end +---@param minp table TODO: заменить тип на класс/вектор координат +---@param maxp table TODO: заменить тип на класс/вектор координат +---@return table function MapGen:process2DRegions(minp, maxp) local cache = {} local width = maxp.x - minp.x + 1 local zSize = maxp.z - minp.z + 1 - + -- Precompute noise for all 2D regions local regionNoiseCache = {} for _, layer in ipairs(self.layersList) do @@ -103,7 +159,7 @@ function MapGen:process2DRegions(minp, maxp) cache[x] = {} for z = minp.z, maxp.z do cache[x][z] = {} - + for _, layer in ipairs(self.layersList) do local bestHeight, bestWeight = nil, 0.0 @@ -139,6 +195,11 @@ function MapGen:process2DRegions(minp, maxp) return cache end +---@param minp table TODO: заменить тип на класс/вектор координат +---@param maxp table TODO: заменить тип на класс/вектор координат +---@param data void TODO: какой тип? +---@param area void +---@param terrainCache void function MapGen:process3DRegions(minp, maxp, data, area, terrainCache) -- Precompute 3D noise for regions local region3DNoise = {} @@ -172,32 +233,32 @@ function MapGen:process3DRegions(minp, maxp, data, area, terrainCache) local columnCache = terrainCache[x][z] local baseIndex = area:index(x, minp.y, z) local yStride = area.ystride - + for y = minp.y, maxp.y do local idx = baseIndex + (y - minp.y) * yStride local processed = false - + for _, layer in ipairs(self.layersList) do if y >= layer.minY and y <= layer.maxY then local surfaceY = columnCache[layer] - + if not surfaceY then - data[idx] = y == layer.minY and - self.materials.impassableSeabed or + data[idx] = y == layer.minY and + self.materials.impassableSeabed or self.materials.impassableWater else -- Set default based on position relative to surface - local default = (y <= surfaceY) and - self.materials.impassableSeabed or + local default = (y <= surfaceY) and + self.materials.impassableSeabed or self.materials.air data[idx] = default - + -- Apply 3D regions (caves/structures) for _, region in ipairs(layer.regions3D) do local temp = region3DNoise[region].temp[y][x][z] local humid = region3DNoise[region].humid[y][x][z] local cave = region3DNoise[region].cave[y][x][z] - + if MapGenUtils.isInRange(temp, region.tempRange) and MapGenUtils.isInRange(humid, region.humidRange) and cave > region.caveThreshold then data[idx] = self.materials.air @@ -205,12 +266,12 @@ function MapGen:process3DRegions(minp, maxp, data, area, terrainCache) end end end - + processed = true break -- Only process one layer per Y position end end - + if not processed then data[idx] = self.materials.air end diff --git a/mods/CORE/MapGen/src/MapGen/Layer.lua b/mods/CORE/MapGen/src/MapGen/Layer.lua index e7d92ea..1684d81 100644 --- a/mods/CORE/MapGen/src/MapGen/Layer.lua +++ b/mods/CORE/MapGen/src/MapGen/Layer.lua @@ -1,42 +1,64 @@ local table, setmetatable = table, setmetatable -local Layer = {} -Layer.__index = Layer +---@class MapGen.Layer +---@field name string +---@field minY number +---@field maxY number +---@field regions2D MapGen.Region.Region2D[] +---@field regions3D MapGen.Region.Region3D[] +local Layer = { + name = nil, + minY = nil, + maxY = nil, + regions2D = nil, + regions3D = nil, +} +---@return MapGen.Layer +---@param name string +---@param minY number +---@param maxY number +---@return MapGen.Layer function Layer:new(name, minY, maxY) - return setmetatable({ + ---@type MapGen.Layer + local instance = setmetatable({ name = name, minY = minY, maxY = maxY, regions2D = {}, regions3D = {} - }, self) + }, {__index = self}) + + return instance end +---@param region MapGen.Region.Region2D function Layer:add2DRegion(region) table.insert(self.regions2D, region) end +---@param region MapGen.Region.Region3D function Layer:add3DRegion(region) table.insert(self.regions3D, region) end +---@return boolean function Layer:contains(x, y, z) - if y < self.minY or y > self.maxY then - return false - end + if y < self.minY or y > self.maxY then + return false + end - for _, region in ipairs(self.regions2D) do - if region:contains2D(x, z) then - return true - end - end + for _, region in ipairs(self.regions2D) do + if region:contains2D(x, z) then -- TODO: ТАКОГО МЕТОДА НИГДЕ НЕТ + return true + end + end - for _, region in ipairs(self.regions3D) do - if region:contains3D(x, y, z) then - return true - end - end + for _, region in ipairs(self.regions3D) do + if region:contains3D(x, y, z) then -- TODO: ТАКОГО МЕТОДА НИГДЕ НЕТ + return true + end + end - return false + return false end diff --git a/mods/CORE/MapGen/src/MapGen/Region.lua b/mods/CORE/MapGen/src/MapGen/Region.lua index 670681c..40513e0 100644 --- a/mods/CORE/MapGen/src/MapGen/Region.lua +++ b/mods/CORE/MapGen/src/MapGen/Region.lua @@ -1,14 +1,21 @@ -local Region = {} -Region.__index = Region - local pairs, setmetatable = pairs, setmetatable +---@class MapGen.Region +local Region = {} + + +---@param params table +---@return MapGen.Region function Region:new(params) - local instance = setmetatable({}, self) + ---@type MapGen.Region + local instance = setmetatable({}, {__index = self}) + for k, v in pairs(params) do instance[k] = v end + instance:initNoises() + return instance end diff --git a/mods/CORE/MapGen/src/MapGen/Region/Region2D.lua b/mods/CORE/MapGen/src/MapGen/Region/Region2D.lua index 61df074..8ff4770 100644 --- a/mods/CORE/MapGen/src/MapGen/Region/Region2D.lua +++ b/mods/CORE/MapGen/src/MapGen/Region/Region2D.lua @@ -1,11 +1,15 @@ -local modInfo = Mod.getInfo() -local Region = modInfo.require()("Region") - local core, setmetatable = core, setmetatable --- 2D Region implementation -local Region2D = setmetatable({}, {__index = Region}) +local modInfo = Mod.getInfo() +---@type MapGen.Region +local Region = modInfo.require("Region") + +---@class MapGen.Region.Region2D : MapGen.Region +local Region2D = Api.getClassExtended(Region, {}) + +---@param params table +---@return MapGen.Region.Region2D function Region2D:new(params) local instance = Region.new(self, params) instance.type = "2d" diff --git a/mods/CORE/MapGen/src/MapGen/Region/Region3D.lua b/mods/CORE/MapGen/src/MapGen/Region/Region3D.lua index 9c96379..5f647f8 100644 --- a/mods/CORE/MapGen/src/MapGen/Region/Region3D.lua +++ b/mods/CORE/MapGen/src/MapGen/Region/Region3D.lua @@ -1,13 +1,17 @@ -local modInfo = Mod.getInfo() -local Region = modInfo.require()("Region") - local core, setmetatable = core, setmetatable --- 3D Region implementation -local Region3D = setmetatable({}, {__index = Region}) +local modInfo = Mod.getInfo() +---@type MapGen.Region +local Region = modInfo.require("Region") + +---@class MapGen.Region.Region3D : MapGen.Region +local Region3D = Api.getClassExtended(Region, {}) + +---@param params table +---@return MapGen.Region.Region3D function Region3D:new(params) - local instance = Region.new(self, params) + local instance = Region:new(params) instance.type = "3d" return setmetatable(instance, {__index = Region3D}) end diff --git a/mods/CORE/MapGen/src/MapGen/Utils.lua b/mods/CORE/MapGen/src/MapGen/Utils.lua index e35d8d2..d56cbd6 100644 --- a/mods/CORE/MapGen/src/MapGen/Utils.lua +++ b/mods/CORE/MapGen/src/MapGen/Utils.lua @@ -1,20 +1,31 @@ local math = math --- Utility class with static methods -local MapGenUtils = { - calculateWeight = function(value, min, max) - local center = (min + max) / 2 - local span = (max - min) / 2 - return 1 - math.abs((value - center) / span) - end, +--- Utility class with static methods +---@class MapGen.Utils +local Utils = {} - ---@return boolean - isInRange = function(value, range) - if value >= range.min and value <= range.max then - return true - end - return false +---@static +---@param value number +---@param min number +---@param max number +---@return number +function Utils.calculateWeight(value, min, max) + local center = (min + max) / 2 + local span = (max - min) / 2 + + return 1 - math.abs((value - center) / span) +end + +---@static +---@param value number +---@param range number +---@return boolean +function Utils.isInRange(value, range) + if value >= range.min and value <= range.max then + return true end -} -return MapGenUtils + return false +end + +return Utils