PlayerInventory & PlayerInventoryUI: adding explanatory annotations and comments to the code. #34

This commit is contained in:
Van
2026-04-13 22:00:27 +03:00
parent f1c82d9220
commit c172198ff7
2 changed files with 64 additions and 27 deletions

View File

@@ -3,6 +3,8 @@ local PrimitiveCraftHandler = Smc.requireCraftSystemPrimitiveCraftHandler()
---@type PlayerInventoryUI ---@type PlayerInventoryUI
local PlayerInventoryUI = Mod.getInfo('smc__ui__player_inventory').require('PlayerInventoryUI') local PlayerInventoryUI = Mod.getInfo('smc__ui__player_inventory').require('PlayerInventoryUI')
-- TODO: перенести обработки в PlayerUI
-- Handling the button click for selecting an item for crafting. -- Handling the button click for selecting an item for crafting.
-- Opens the item description and allows you to craft the selected item. -- Opens the item description and allows you to craft the selected item.
PlayerInventoryUI:registerOnFormFieldActionMatch('.+::%S+::item_button',function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('.+::%S+::item_button',function(player, fieldName, fieldValue)

View File

@@ -6,7 +6,6 @@ local require = Mod.getInfo('smc__ui__player_inventory').require
---@alias PlayerInventoryUI.TabType 'left'|'right' ---@alias PlayerInventoryUI.TabType 'left'|'right'
---@alias PlayerInventoryUI.getTabFunc fun(self:PlayerInventoryUI,playerName:string,tabType:PlayerInventoryUI.TabType):Formspec ---@alias PlayerInventoryUI.getTabFunc fun(self:PlayerInventoryUI,playerName:string,tabType:PlayerInventoryUI.TabType):Formspec
---@alias PlayerInventoryUI.TabName 'select_tab_menu'|'bag_tab'|'craft_tab'|'equip_tab'|'ref_tab' ---@alias PlayerInventoryUI.TabName 'select_tab_menu'|'bag_tab'|'craft_tab'|'equip_tab'|'ref_tab'
---@type PlayerInventoryUI.getTabFunc ---@type PlayerInventoryUI.getTabFunc
@@ -54,45 +53,45 @@ local tabButtonTextures = {
} }
} }
---@param tabName PlayerInventoryUI.TabName ---Returns the formspec definition for the compact (single tab)
local function getTab(tabName) ---version of the player's inventory.
if tabName == nil then
---@type PlayerInventoryUI.TabName
tabName = 'select_tab_menu'
end
local tab = tabs[tabName]
assert(tab ~= nil, ('The tab with the `%s` does not exist.'):format(tabName))
return tab
end
---@param self PlayerInventoryUI ---@param self PlayerInventoryUI
---@param playerName string ---@param playerName string
---@return string ---@return string
local function getCompactForm(self, playerName) local function getCompactForm(self, playerName)
-- We geet the name of the selected (active) tab.
-- The left tab is considered the primary tab (shown in the compact version).
--
-- If the tab is not specified, the equipment tab will be opened by default.
---@type PlayerInventoryUI.TabName ---@type PlayerInventoryUI.TabName
local leftTabName = self:getContex(playerName, 'left_tab_name') or 'craft_tab' local leftTabName = self:getContex(playerName, 'left_tab_name') or 'equip_tab'
-- TODO: убрать, если будет не нужно
local leftTabIsBlock = self:getContex(playerName, 'left_tab_is_block') local leftTabIsBlock = self:getContex(playerName, 'left_tab_is_block')
-- Create an instance of the inventory form.
local InventoryForm = Formspec:new({ local InventoryForm = Formspec:new({
size = {x=14, y=12.5}, size = {x=14, y=12.5},
position = {x=0.5, y=0.55}, position = {x=0.5, y=0.55},
noPrepend = true, noPrepend = true,
}) })
-- We get a table for textures for tab selection buttons according to the active tab.
local leftTabButtonTextures = tabButtonTextures[leftTabName] local leftTabButtonTextures = tabButtonTextures[leftTabName]
InventoryForm: InventoryForm:
-- Removing the inventory background color:
bgcolor('#00000000', 'neither'): bgcolor('#00000000', 'neither'):
-- A permanent part of the inventory:
background(0, 0.5, 14, 12.5, 'player_inventory_compact_middle_background.png', false): background(0, 0.5, 14, 12.5, 'player_inventory_compact_middle_background.png', false):
listColors('#00000000', '#e1b69150'): listColors('#00000000', '#e1b69150'):
imageButton(13, 9.75, 0.5, 1, 'player_inventory_compact_mode_button_on.png', 'change_compact_mode'):
list('current_player', 'main', 1.5,9.75, 9,1): list('current_player', 'main', 1.5,9.75, 9,1):
list('current_player', 'main', 1.5,11.25, 9,1, 9): list('current_player', 'main', 1.5,11.25, 9,1, 9):
-- Inventory mode switch button (compact/full):
imageButton(13, 9.75, 0.5, 1, 'player_inventory_compact_mode_button_on.png', 'change_compact_mode'):
-- Tab:
container(tabs[leftTabName](self, playerName, 'left'), 1.5, 0.5): container(tabs[leftTabName](self, playerName, 'left'), 1.5, 0.5):
-- Selection buttons for the left panel: -- Selection buttons for the (left) panel:
imageButton(1.5,0,2,0.5, leftTabButtonTextures[1],'select_left_craft_tab', core.colorize('#e1b691','craft')): imageButton(1.5,0,2,0.5, leftTabButtonTextures[1],'select_left_craft_tab', core.colorize('#e1b691','craft')):
imageButton(3.5,0,2,0.5, leftTabButtonTextures[2], 'select_left_equip_tab', core.colorize('#e1b691','equip')): imageButton(3.5,0,2,0.5, leftTabButtonTextures[2], 'select_left_equip_tab', core.colorize('#e1b691','equip')):
imageButton(5.5,0,2,0.5, leftTabButtonTextures[3], 'select_left_bag_tab', core.colorize('#e1b691','bags')): imageButton(5.5,0,2,0.5, leftTabButtonTextures[3], 'select_left_bag_tab', core.colorize('#e1b691','bags')):
@@ -101,34 +100,50 @@ local function getCompactForm(self, playerName)
return InventoryForm:toString() return InventoryForm:toString()
end end
---Returns the formspec definition for the full (two tab)
---version of the player's inventory.
---@param self PlayerInventoryUI ---@param self PlayerInventoryUI
---@param playerName string ---@param playerName string
---@return string ---@return string
local function getFullForm(self, playerName) local function getFullForm(self, playerName)
-- We get the names of the active tabs (left and right).
-- The tabs are identical, but when switching the inventory
-- to compact mode, the left tab becomes the primary one.
--
-- The default values ​​are:
-- * left tab - equipment;
-- * right tab - crafting menu.
---@type PlayerInventoryUI.TabName ---@type PlayerInventoryUI.TabName
local leftTabName = self:getContex(playerName, 'left_tab_name') or 'craft_tab' local leftTabName = self:getContex(playerName, 'left_tab_name') or 'craft_tab'
---@type PlayerInventoryUI.TabName ---@type PlayerInventoryUI.TabName
local rightTabName = self:getContex(playerName, 'right_tab_name') or 'craft_tab' local rightTabName = self:getContex(playerName, 'right_tab_name') or 'craft_tab'
-- TODO: убрать, если будет не нужно
local leftTabIsBlock = self:getContex(playerName, 'left_tab_is_block') local leftTabIsBlock = self:getContex(playerName, 'left_tab_is_block')
local rightTabIsBlock = self:getContex(playerName, 'right_tab_is_block') local rightTabIsBlock = self:getContex(playerName, 'right_tab_is_block')
-- Create an instance of the inventory form.
local InventoryForm = Formspec:new({ local InventoryForm = Formspec:new({
size = {x=22, y=12.5}, size = {x=22, y=12.5},
position = {x=0.5, y=0.55}, position = {x=0.5, y=0.55},
noPrepend = true, noPrepend = true,
}) })
-- We get texture tables for the tab selection buttons depending on the active tabs.
local leftTabButtonTextures = tabButtonTextures[leftTabName] local leftTabButtonTextures = tabButtonTextures[leftTabName]
local rightTabButtonTextures = tabButtonTextures[rightTabName] local rightTabButtonTextures = tabButtonTextures[rightTabName]
InventoryForm: InventoryForm:
-- Removing the inventory background color:
bgcolor('#00000000', 'neither'): bgcolor('#00000000', 'neither'):
-- A permanent part of the inventory:
background(0, 9.5, 22, 3, 'player_inventory_middle_background.png', false): background(0, 9.5, 22, 3, 'player_inventory_middle_background.png', false):
listColors('#00000000', '#e1b69150'): listColors('#00000000', '#e1b69150'):
imageButton(17, 9.75, 0.5, 1, 'player_inventory_compact_mode_button_off.png', 'change_compact_mode'):
list('current_player', 'main', 5.5,9.75, 9,1): list('current_player', 'main', 5.5,9.75, 9,1):
list('current_player', 'main', 5.5,11.25, 9,1, 9): list('current_player', 'main', 5.5,11.25, 9,1, 9):
-- Inventory mode switch button (compact/full):
imageButton(17, 9.75, 0.5, 1, 'player_inventory_compact_mode_button_off.png', 'change_compact_mode'):
-- Tabs:
container(tabs[leftTabName](self, playerName, 'left'), 0, 0.5): container(tabs[leftTabName](self, playerName, 'left'), 0, 0.5):
container(tabs[rightTabName](self, playerName, 'right'), 11, 0.5): container(tabs[rightTabName](self, playerName, 'right'), 11, 0.5):
-- Selection buttons for the left panel: -- Selection buttons for the left panel:
@@ -136,6 +151,7 @@ local function getFullForm(self, playerName)
imageButton(2,0,2,0.5, leftTabButtonTextures[2], 'select_left_equip_tab', core.colorize('#e1b691','equip')): imageButton(2,0,2,0.5, leftTabButtonTextures[2], 'select_left_equip_tab', core.colorize('#e1b691','equip')):
imageButton(4,0,2,0.5, leftTabButtonTextures[3], 'select_left_bag_tab', core.colorize('#e1b691','bags')): imageButton(4,0,2,0.5, leftTabButtonTextures[3], 'select_left_bag_tab', core.colorize('#e1b691','bags')):
imageButton(6,0,2,0.5, leftTabButtonTextures[4], 'select_left_ref_tab', core.colorize('#e1b691','refs')): imageButton(6,0,2,0.5, leftTabButtonTextures[4], 'select_left_ref_tab', core.colorize('#e1b691','refs')):
-- Selection buttons for the right panel:
imageButton(11,0,2,0.5, rightTabButtonTextures[1],'select_right_craft_tab', core.colorize('#e1b691','craft')): imageButton(11,0,2,0.5, rightTabButtonTextures[1],'select_right_craft_tab', core.colorize('#e1b691','craft')):
imageButton(13,0,2,0.5, rightTabButtonTextures[2], 'select_right_equip_tab', core.colorize('#e1b691','equip')): imageButton(13,0,2,0.5, rightTabButtonTextures[2], 'select_right_equip_tab', core.colorize('#e1b691','equip')):
imageButton(15,0,2,0.5, rightTabButtonTextures[3], 'select_right_bag_tab', core.colorize('#e1b691','bags')): imageButton(15,0,2,0.5, rightTabButtonTextures[3], 'select_right_bag_tab', core.colorize('#e1b691','bags')):
@@ -144,23 +160,37 @@ local function getFullForm(self, playerName)
return InventoryForm:toString() return InventoryForm:toString()
end end
---Returns the inventory formspec definition
---depending on the selected inventory mod (compact/full).
---
---The selected inventory mode is contained in the context of the `PlayerInventoryUI` UI class.
---@param self PlayerInventoryUI ---@param self PlayerInventoryUI
---@param playerName string ---@param playerName string
---@return string ---@return string
local function getFormSpecString(self, playerName) local function getFormSpecString(self, playerName)
-- We get the selected inventory mode.
-- * `true` - compact mode
-- * `false` - full mode
---@type boolean ---@type boolean
local compactMode = self:getContex(playerName, 'compact_mode') local compactMode = self:getContex(playerName, 'compact_mode')
-- If the mode is not selected...
if compactMode == nil then if compactMode == nil then
-- ...by default it will be `true` (compact mode).
compactMode = true compactMode = true
end end
-- If compact mode is selected...
if compactMode then if compactMode then
-- ...return the compact inventory definition.
return getCompactForm(self, playerName) return getCompactForm(self, playerName)
else else
-- ...else we return the full version of the inventory.
return getFullForm(self, playerName) return getFullForm(self, playerName)
end end
end end
---Context keys for the `PlayerInventoryUI` class.
---@alias PlayerInventoryUI.ContexKey ---@alias PlayerInventoryUI.ContexKey
--- 'compact_mode'| --- 'compact_mode'|
--- ---
@@ -186,16 +216,23 @@ end
---@field setContex fun(self:PlayerInventoryUI,player:string|Player,key:PlayerInventoryUI.ContexKey,value:any) ---@field setContex fun(self:PlayerInventoryUI,player:string|Player,key:PlayerInventoryUI.ContexKey,value:any)
local PlayerInventoryUI = BaseUI:new('', getFormSpecString, false) local PlayerInventoryUI = BaseUI:new('', getFormSpecString, false)
-- We are overriding the `BaseUI.showForm`.
local showForm = PlayerInventoryUI.showForm local showForm = PlayerInventoryUI.showForm
function PlayerInventoryUI:showForm(playerName) function PlayerInventoryUI:showForm(playerName)
-- We get a player by his name.
local player = core.get_player_by_name(playerName) local player = core.get_player_by_name(playerName)
assert(player ~= nil) assert(player ~= nil)
-- We overwrite the player's inventory definition so that the updated inventory
-- is shown to the player when they press the "open inventory" key.
player:set_inventory_formspec(PlayerInventoryUI:getFormSpecString(playerName)) player:set_inventory_formspec(PlayerInventoryUI:getFormSpecString(playerName))
-- We call the standard `BaseUI.showForm` function for the standard operation.
return showForm(self, playerName) return showForm(self, playerName)
end end
-- Handling the press of the inventory mode change button.
PlayerInventoryUI:registerOnFormFieldAction('change_compact_mode', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldAction('change_compact_mode', function(player, fieldName, fieldValue)
local playerName = player:get_player_name() local playerName = player:get_player_name()
@@ -208,6 +245,7 @@ PlayerInventoryUI:registerOnFormFieldAction('change_compact_mode', function(play
PlayerInventoryUI:showForm(playerName) PlayerInventoryUI:showForm(playerName)
end) end)
-- Handling the left inventory tab selection button press.
PlayerInventoryUI:registerOnFormFieldActionMatch('select_left_%S+', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('select_left_%S+', function(player, fieldName, fieldValue)
local tabName = stringMatch(fieldName, 'select_%S+_(%S+_%S+)') local tabName = stringMatch(fieldName, 'select_%S+_(%S+_%S+)')
assert(tabName ~= nil) assert(tabName ~= nil)
@@ -218,13 +256,7 @@ PlayerInventoryUI:registerOnFormFieldActionMatch('select_left_%S+', function(pla
PlayerInventoryUI:showForm(playerName) PlayerInventoryUI:showForm(playerName)
end) end)
PlayerInventoryUI:registerOnFormFieldAction('close_right_tab', function(player, fieldName, fieldValue) -- Handling the right inventory tab selection button press.
local playerName = player:get_player_name()
PlayerInventoryUI:setContex(playerName, 'right_tab_name', 'select_tab_menu')
PlayerInventoryUI:showForm(playerName)
end)
PlayerInventoryUI:registerOnFormFieldActionMatch('select_right_%S+', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('select_right_%S+', function(player, fieldName, fieldValue)
local tabName = stringMatch(fieldName, 'select_%S+_(%S+_%S+)') local tabName = stringMatch(fieldName, 'select_%S+_(%S+_%S+)')
assert(tabName ~= nil) assert(tabName ~= nil)
@@ -235,6 +267,7 @@ PlayerInventoryUI:registerOnFormFieldActionMatch('select_right_%S+', function(pl
PlayerInventoryUI:showForm(playerName) PlayerInventoryUI:showForm(playerName)
end) end)
-- Handling the click of the button to turning back through the crafting menu pages.
PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_back', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_back', function(player, fieldName, fieldValue)
local tabType = stringMatch(fieldName, '(%S+)::page_back') local tabType = stringMatch(fieldName, '(%S+)::page_back')
assert(tabType == 'left' or tabType == 'right') assert(tabType == 'left' or tabType == 'right')
@@ -251,6 +284,7 @@ PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_back', function(play
PlayerInventoryUI:showForm(playerName) PlayerInventoryUI:showForm(playerName)
end) end)
-- Handling the click of the button to turning forward through the crafting menu pages.
PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_forward', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_forward', function(player, fieldName, fieldValue)
local tabType = stringMatch(fieldName, '(%S+)::page_forward') local tabType = stringMatch(fieldName, '(%S+)::page_forward')
assert(tabType == 'left' or tabType == 'right') assert(tabType == 'left' or tabType == 'right')
@@ -267,6 +301,7 @@ PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::page_forward', function(p
PlayerInventoryUI:showForm(playerName) PlayerInventoryUI:showForm(playerName)
end) end)
-- Processing closing of the selected item group in the crafting menu (returning to the main list of crafts).
PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::close_group', function(player, fieldName, fieldValue) PlayerInventoryUI:registerOnFormFieldActionMatch('%S+::close_group', function(player, fieldName, fieldValue)
local tabType = stringMatch(fieldName, '(%S+)::close_group') local tabType = stringMatch(fieldName, '(%S+)::close_group')
assert(tabType == 'left' or tabType == 'right') assert(tabType == 'left' or tabType == 'right')