Merge pull request #2 from SGG-Modding/new_default

New Default - Managed boilerplate edition

Author: nbusseneau

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added dedicated `ready` and `reload` files so `main.lua` can be ignored for simple mods.
+- Added a stub `defs.lua` as a reminder to document the plugin if relevant.
+
+### Changed
+
+- Default template is more up-to-date.
+
 ## [0.5.1] - 2024-05-15
 
 ### Fixed

src/src/def.lua

@@ -0,0 +1,12 @@
+---@meta AuthorName-ModName
+local public = {}
+
+-- document whatever you made publicly available to other plugins here
+-- use luaCATS annotations and give descriptions where appropriate
+--  e.g. 
+--	---@param a integer helpful description
+--	---@param b string helpful description
+--	---@return table c helpful description
+--	function public.do_stuff(a, b)
+
+return public

src/src/main.lua

@@ -1,80 +1,58 @@
----@module 'SGG_Modding-ENVY'
-local envy = rom.mods['SGG_Modding-ENVY']
+---@meta _
+-- grabbing our dependencies,
+-- these funky (---@) comments are just there
+--	 to help VS Code find the definitions of things
+
+---@diagnostic disable-next-line: undefined-global
+local mods = rom.mods
 
 ---@module 'SGG_Modding-ENVY-auto'
-envy.auto(); _ENV = private
+mods['SGG_Modding-ENVY'].auto()
+-- ^ this gives us `public` and `import`, among others
+--	and makes all globals we define private to this plugin.
+---@diagnostic disable: lowercase-global
 
----@module 'SGG_Modding-ReLoad'
-local reload = rom.mods['SGG_Modding-ReLoad']
-local loader = reload.auto_multiple()
-
----@module 'SGG_Modding-Chalk'
-local chalk = rom.mods["SGG_Modding-Chalk"]
+---@diagnostic disable-next-line: undefined-global
+rom = rom
+---@diagnostic disable-next-line: undefined-global
+_PLUGIN = PLUGIN
 
 ---@module 'SGG_Modding-Hades2GameDef-Globals'
-local game = rom.game
+game = rom.game
 
 ---@module 'SGG_Modding-SJSON'
-local sjson = rom.mods['SGG_Modding-SJSON']
-
+sjson = mods['SGG_Modding-SJSON']
 ---@module 'SGG_Modding-ModUtil'
-local modutil = rom.mods['SGG_Modding-ModUtil']
+modutil = mods['SGG_Modding-ModUtil']
 
----@module 'config'
-local config = chalk.auto_lua_toml()
-public.config = config
-
-local function on_ready_setup()
-	-- what to do when we are ready, but not re-do on reload.
-	
-	if not config.enabled then return end
-	
-	local file = rom.path.combine(rom.paths.Content, 'Game/Text/en/ShellText.en.sjson')
+---@module 'SGG_Modding-Chalk'
+chalk = mods["SGG_Modding-Chalk"]
+---@module 'SGG_Modding-ReLoad'
+reload = mods['SGG_Modding-ReLoad']
 
-	sjson.hook(file, function(...)
-		return private.sjson_ShellText(...)
-	end)
-end
+---@module 'config'
+config = chalk.auto 'config.lua'
+-- ^ this updates our `.cfg` file in the config folder!
+public.config = config -- so other mods can access our config
 
-local function on_ready_final()
+local function on_ready()
 	-- what to do when we are ready, but not re-do on reload.
-
-	if not config.enabled then return end
-	
-	modutil.mod.Path.Wrap("SetupMap", function(base, ...)
-		return private.wrap_SetupMap(base, ...)
-	end)
+	if config.enabled == false then return end
 
-	game.OnControlPressed({'Gift', function(...)
-		return private.trigger_Gift(...)
-	end})
+	import 'ready.lua'
 end
 
-local function on_reload_setup()
+local function on_reload()
 	-- what to do when we are ready, but also again on every reload.
 	-- only do things that are safe to run over and over.
 
-	function private.sjson_ShellText(data)
-		for _,v in ipairs(data.Texts) do
-			if v.Id == 'MainMenuScreen_PlayGame' then
-				v.DisplayName = 'Test ' .. _PLUGIN.guid
-				break
-			end
-		end
-	end
-
-	function private.wrap_SetupMap(base)
-		print('Map is loading, here we might load some packages.')
-		return base()
-	end
-
-	function private.trigger_Gift()
-		modutil.mod.Hades.PrintOverhead(config.message)
-	end
+	import 'reload.lua'
 end
 
-loader.load('plugin is ready', on_ready_setup, on_reload_setup)
+-- this allows us to limit certain functions to not be reloaded.
+local loader = reload.auto_single()
 
+-- this runs only when modutil and the game's lua is ready
 modutil.on_ready_final(function()
-	loader.load('game is ready', on_ready_final)
+	loader.load(on_ready, on_reload)
 end)

src/src/ready.lua

@@ -0,0 +1,22 @@
+---@meta _
+-- globals we define are private to our plugin!
+---@diagnostic disable: lowercase-global
+
+-- here is where your mod sets up all the things it will do.
+-- this file will not be reloaded if it changes during gameplay
+-- 	so you will most likely want to have it reference
+--	values and functions later defined in `reload.lua`.
+
+local file = rom.path.combine(rom.paths.Content, 'Game/Text/en/ShellText.en.sjson')
+
+sjson.hook(file, function(data)
+	return sjson_ShellText(data)
+end)
+
+modutil.mod.Path.Wrap("SetupMap", function(base)
+	return wrap_SetupMap(base)
+end)
+
+game.OnControlPressed({'Gift', function()
+	return trigger_Gift()
+end})

src/src/reload.lua

@@ -0,0 +1,25 @@
+---@meta _
+-- globals we define are private to our plugin!
+---@diagnostic disable: lowercase-global
+
+-- this file will be reloaded if it changes during gameplay,
+-- 	so only assign to values or define things here.
+
+function sjson_ShellText(data)
+	for _,v in ipairs(data.Texts) do
+		if v.Id == 'MainMenuScreen_PlayGame' then
+			v.DisplayName = 'Test ' .. _PLUGIN.guid
+			break
+		end
+	end
+end
+
+function wrap_SetupMap(base)
+	print('Map is loading, here we might load some packages.')
+	-- game.LoadPackages({Name = package_name_string})
+	return base()
+end
+
+function trigger_Gift()
+	modutil.mod.Hades.PrintOverhead(config.message)
+end

src/thunderstore.toml

@@ -11,8 +11,9 @@ websiteUrl = "https://github.com/AuthorName/ModName"
 containsNsfwContent = false
 
 [package.dependencies]
+Hell2Modding-Hell2Modding = "1.0.26"
 SGG_Modding-ENVY = "1.0.0"
-SGG_Modding-Chalk = "1.0.0"
+SGG_Modding-Chalk = "2.0.2"
 SGG_Modding-ReLoad = "1.0.1"
 SGG_Modding-SJSON = "1.0.0"
 SGG_Modding-ModUtil = "3.1.0"