feat: BootLoadingMode config option

BootLoadingMode config option for adjusting boot preload behavior for portraits, palettes and stage previews.
* 0 = Off       : preload everything before entering menus / select. (default)
* 1 = Wait      : preload in the background, but wait before entering select screen.
                  If logo/intro uses waitforloading = 1, that is used instead.
* 2 = Immediate : enter menus and select screen immediately and load assets in the background.

When BootLoadingMode = 2, highlighted characters are prioritized during selection. Once the highlighted character finishes preloading, normal low-priority queue order resumes. Moving the cursor deprioritizes the previously highlighted character unless another cursor still highlights it.

Author: K4thos

external/script/main.lua

@@ -170,6 +170,7 @@ options.t_itemname = {
 			--modifyGameOption('Config.EscOpensMenu', true)
 			modifyGameOption('Config.VsScreenLoading', false)
 			modifyGameOption('Config.TurnsLoading', false)
+			--modifyGameOption('Config.BootLoadingMode', 0)
 			--modifyGameOption('Config.FirstRun', false)
 			--modifyGameOption('Config.WindowTitle', "Ikemen GO")
 			--modifyGameOption('Config.WindowIcon', {"external/icons/IkemenCylia_256.png", "external/icons/IkemenCylia_96.png", "external/icons/IkemenCylia_48.png"})

external/script/options.lua

@@ -501,6 +501,7 @@ function start.f_setStage(num, assigned)
 		end
 	end
 	selectStage(num)
+	main.f_preloadBoostStage(num)
 	return num
 end
 
@@ -1699,6 +1700,9 @@ function start.f_selectMode()
 	start.f_selectReset(true)
 	while true do
 		--select screen
+		if gameOption('Config.BootLoadingMode') == 1 then
+			main.f_waitForPreloads()
+		end
 		if not start.f_selectScreen() then
 			sndPlay(motif.Snd, motif.select_info.cancel.snd[1], motif.select_info.cancel.snd[2])
 			bgReset(motif[main.background].BGDef)
@@ -1873,6 +1877,12 @@ function start.f_selectReset(hardReset, preserveProgress)
 	t_reservedChars = {{}, {}}
 	cursorActive = {}
 	cursorDone = {}
+	if main.preload ~= nil and main.preload.charHighlight ~= nil then
+		for _, ref in pairs(main.preload.charHighlight) do
+			queueCharPreload(ref, 1)
+		end
+		main.preload.charHighlight = {}
+	end
 	t_portraitPriority = {1, 1}
 	if start.challenger == 0 and not preserveProgress then
 		start.t_roster = {}
@@ -2332,6 +2342,41 @@ end
 --;===========================================================
 --; SELECT SCREEN
 --;===========================================================
+local function refreshActiveFacePortraits()
+	for side = 1, 2 do
+		for k, v in ipairs(start.p[side].t_selCmd) do
+			local member = main.f_tableLength(start.p[side].t_selected) + k
+			if main.coop and (side == 1 or gameMode('versuscoop')) then
+				member = k
+			end
+			local st = start.p[side].t_selTemp[member]
+			local player = v.player
+			local selRef = start.c[player].selRef
+			if v.selectState == 0 and st ~= nil and selRef ~= nil and st.ref == selRef then
+				local state = getCharPreloadStatus(selRef)
+				if state == 'ready' then
+					local pn = 2 * (member - 1) + side
+					local pCfg = f_getMotifP(motif.select_info, pn, side)
+					local updated = false
+					if st.face_data == nil then
+						st.face_anim = pCfg.face.anim
+						st.face_data = start.f_animGet(selRef, side, member, pCfg.face, nil, true, st.face_data)
+						updated = updated or st.face_data ~= nil
+					end
+					if st.face2_data == nil then
+						st.face2_anim = pCfg.face2.anim
+						st.face2_data = start.f_animGet(selRef, side, member, pCfg.face2, nil, true, st.face2_data)
+						updated = updated or st.face2_data ~= nil
+					end
+					if updated then
+						start.needUpdateDrawList = true
+					end
+				end
+			end
+		end
+	end
+end
+
 function start.updateDrawList()
 	local drawList = {}
 
@@ -2496,6 +2541,8 @@ function start.f_selectScreen()
 	start.needUpdateDrawList = false
 
 	while not selScreenEnd do
+		main.f_preloadTick(4)
+		refreshActiveFacePortraits()
 		counter = counter + 1
 		--draw clearcolor
 		clearColor(motif.selectbgdef.bgclearcolor[1], motif.selectbgdef.bgclearcolor[2], motif.selectbgdef.bgclearcolor[3])
@@ -2688,10 +2735,29 @@ function start.f_selectScreen()
 					)
 				end
 				if not stageEnd then
-					if (getInput(-1, motif.select_info.done.key) and not screenDelayInterrupted) or timerSelect == -1 then
-						sndPlay(motif.Snd, motif.select_info.stage.done.snd[1], motif.select_info.stage.done.snd[2])
-						stageTextData = motif.select_info.stage.done.TextSpriteData
-						stageEnd = true
+					local canConfirmStage = (getInput(-1, motif.select_info.done.key) and not screenDelayInterrupted) or timerSelect == -1
+					if canConfirmStage then
+						local preloadReady = true
+						if stageListNo > 0 then
+							local stageRef = main.t_selectableStages[stageListNo]
+							local state = getStagePreloadStatus(stageRef)
+							preloadReady = state == 'ready'
+							if not preloadReady then
+								main.f_preloadBoostStage(stageRef)
+							else
+								if main.f_materializeStagePortrait(stageRef) then
+									start.needUpdateDrawList = true
+								end
+							end
+						end
+						if not preloadReady and getInput(-1, motif.select_info.done.key) and not screenDelayInterrupted then
+							sndPlay(motif.Snd, motif.select_info.cancel.snd[1], motif.select_info.cancel.snd[2])
+						end
+						if preloadReady then
+							sndPlay(motif.Snd, motif.select_info.stage.done.snd[1], motif.select_info.stage.done.snd[2])
+							stageTextData = motif.select_info.stage.done.TextSpriteData
+							stageEnd = true
+						end
 					elseif stageActiveCount < motif.select_info.stage.active.switchtime then --delay change
 						stageActiveCount = stageActiveCount + 1
 					else
@@ -3281,6 +3347,7 @@ function start.f_selectMenu(side, cmd, player, member, selectState)
 			start.c[player].selX, start.c[player].selY = start.f_cellMovement(start.c[player].selX, start.c[player].selY, cmd, side, start.f_getCursorData(player).cursor.move.snd)
 			start.c[player].cell = start.c[player].selX + motif.select_info.columns * start.c[player].selY
 			start.c[player].selRef = start.f_selGrid(start.c[player].cell + 1).char_ref
+			main.f_preloadSetCharHighlight(player, start.c[player].selRef)
 			-- temp data not existing yet
 			if start.p[side].t_selTemp[member] == nil then
 				t_portraitPriority[side] = member
@@ -3299,6 +3366,9 @@ function start.f_selectMenu(side, cmd, player, member, selectState)
 				local timerExpired = motif.select_info.timer.count ~= -1 and timerSelect == -1
 				needUpdateDrawList = slotChanged
 				local velCopy = false
+				if slotChanged then
+					start.c[player].selRef = start.f_selGrid(start.c[player].cell + 1).char_ref
+				end
 				if timerExpired then
 					if start.c[player].selRef == nil or main.t_selChars[start.c[player].selRef + 1] == nil then
 						start.c[player].selRef = start.f_randomChar(side)
@@ -3354,6 +3424,7 @@ function start.f_selectMenu(side, cmd, player, member, selectState)
 				else
 					start.p[side].t_selTemp[member].inRandom = false
 				end
+				main.f_preloadSetCharHighlight(player, start.c[player].selRef)
 				-- update anim data
 				if updateAnim then
 					local face_data = velCopy and start.p[side].t_selTemp[member].face_data or nil
@@ -3362,7 +3433,26 @@ function start.f_selectMenu(side, cmd, player, member, selectState)
 					start.p[side].t_selTemp[member].face2_data = start.f_animGet(start.c[player].selRef, side, member, pCfg.face2, nil, true, face2_data)
 				end
 				-- cell selected or select screen timer reached 0
-				if (slotSelected and start.f_selGrid(start.c[player].cell + 1).char ~= nil and start.f_selGrid(start.c[player].cell + 1).hidden ~= 2) or timerExpired then
+				local canConfirm = (slotSelected and start.f_selGrid(start.c[player].cell + 1).char ~= nil and start.f_selGrid(start.c[player].cell + 1).hidden ~= 2) or timerExpired
+				if canConfirm then
+					local preloadReady = true
+					if start.c[player].selRef ~= nil then
+						local state = getCharPreloadStatus(start.c[player].selRef)
+						preloadReady = state == 'ready'
+						if not preloadReady then
+							main.f_preloadBoostChar(start.c[player].selRef)
+						else
+							main.f_materializeCharByRef(start.c[player].selRef)
+						end
+					end
+					if not preloadReady then
+						if slotSelected then
+							sndPlay(motif.Snd, motif.select_info.cancel.snd[1], motif.select_info.cancel.snd[2])
+						end
+						canConfirm = false
+					end
+				end
+				if canConfirm then
 					if motif.select_info.paletteselect ~= 0 then
 						timerSelect = motif.select_info.timer.displaytime
 					end
@@ -3476,6 +3566,7 @@ function start.f_selectMenu(side, cmd, player, member, selectState)
 				pn = start.f_getPlayerNo(side, member),
 				cursor = {start.c[player].selX, start.c[player].selY},
 			}
+			main.f_preloadSetCharHighlight(player, nil)
 			hook.run("start.f_selectMenu.selected", side, member, start.p[side].t_selected[member], start.p[side], player)
 			if not gameOption('Options.Team.Duplicates') then
 				t_reservedChars[side][start.c[player].selRef] = true
@@ -3572,6 +3663,9 @@ function start.f_stageMenu()
 		animReset(main.t_selStages[main.t_selectableStages[stageListNo]].anim_data)
 		animUpdate(main.t_selStages[main.t_selectableStages[stageListNo]].anim_data)
 	end
+	if stageListNo > 0 then
+		main.f_preloadBoostStage(main.t_selectableStages[stageListNo])
+	end
 end
 
 --;===========================================================
@@ -3755,6 +3849,7 @@ function start.f_selectVersus(active, t_orderSelect, loadStartArg)
 		end
 	end
 	while true do
+		main.f_preloadTick(4)
 		local snd = false
 		-- CPU order select: randomize first, then selectChar() using randomized slot order
 		for side = 1, 2 do

external/script/start.lua

@@ -115,6 +115,7 @@ type Config struct {
 		EscOpensMenu      bool     `ini:"EscOpensMenu" sync:"host"`
 		VsScreenLoading   bool     `ini:"VsScreenLoading" sync:"host"`
 		TurnsLoading      bool     `ini:"TurnsLoading" sync:"host"`
+		BootLoadingMode   int32    `ini:"BootLoadingMode" sync:"host"`
 		FirstRun          bool     `ini:"FirstRun"`
 		WindowTitle       string   `ini:"WindowTitle"`
 		WindowIcon        []string `ini:"WindowIcon"`

src/config.go

@@ -640,7 +640,11 @@ type TitleInfoProperties struct {
 	Cancel struct {
 		Snd [2]int32 `ini:"snd" default:"-1,0"`
 	} `ini:"cancel"`
-	Loading TextProperties `ini:"loading"`
+	Loading struct {
+		TextProperties
+		Wait       AnimationTextProperties `ini:"wait"`
+		Storyboard string `ini:"storyboard" lookup:"def,,data/"`
+	} `ini:"loading"`
 	Footer  struct {
 		Title   TextProperties    `ini:"title"`
 		Info    TextProperties    `ini:"info"`
@@ -2196,6 +2200,8 @@ func (m *Motif) customResultsScreenSections() []string {
 func (m *Motif) overrideParams() {
 	// Define inheritance rules (section/prefix based).
 	specs := []InheritSpec{
+		// [Title Info]
+		{SrcSec: "Title Info", SrcPrefix: "loading.", DstSec: "Title Info", DstPrefix: "loading.wait."},
 		// [Option Info]
 		{SrcSec: "Option Info", SrcPrefix: "menu.", DstSec: "Option Info", DstPrefix: "keymenu."},
 		// [Select Info]

src/motif.go

@@ -127,6 +127,12 @@ EscOpensMenu        = 1
 VsScreenLoading     = 0
 ; Toggles Turns member loading during the match.
 TurnsLoading        = 0
+; Boot preload behavior for portraits, palettes and stage previews.
+; 0 = Off       : preload everything before entering menus / select. (default)
+; 1 = Wait      : preload in the background, but wait before entering select screen.
+;                 If logo/intro uses waitforloading = 1, that is used instead.
+; 2 = Immediate : enter menus and select screen immediately and load assets in the background.
+BootLoadingMode     = 0
 ; This is 1 the first time you run IKEMEN.
 FirstRun            = 1
 ; Title of the application window.

src/resources/defaultConfig.ini

@@ -460,6 +460,27 @@
 	loading.window = 
 	loading.localcoord = 
 
+	; Boot-loading wait element rendered on black screen when BootLoadingMode = 1
+	loading.wait.anim = -1
+	loading.wait.spr = -1, 0
+	loading.wait.font = default-3x5.def, 0, -1, 191, 191, 191, 255, -1
+	loading.wait.offset = 0, 0
+	loading.wait.facing = 1
+	loading.wait.scale = 1.0, 1.0
+	loading.wait.xshear = 0
+	loading.wait.angle = 0
+	loading.wait.xangle = 0
+	loading.wait.yangle = 0
+	loading.wait.projection = orthographic
+	loading.wait.focallength = 2048
+	loading.wait.text = LOADING...
+	loading.wait.layerno = 0
+	loading.wait.window = 
+	loading.wait.localcoord = 320, 240
+
+	; Optional storyboard used by BootLoadingMode = 1 instead of loading.wait
+	loading.storyboard =
+
 	; Footer parameters control rendering of engine version info. Separated into
 	; 3 elements to allow left/center/right text align at the same time.
 	; Unless overridden, offsets and version text are set when loading the motif.

src/resources/defaultMotif.ini

@@ -1163,7 +1163,14 @@ func systemScriptInit(l *lua.LState) {
 		@treturn Anim|nil anim A new `Anim` userdata wrapping the preloaded animation,
 		  or `nil` if no matching animation exists.
 		function animGetPreloadedCharData(charRef, group, number, keepLoop) end*/
-		if anim := sys.sel.GetChar(int(numArg(l, 1))).anims.get(int32(numArg(l, 2)), int32(numArg(l, 3))); anim != nil {
+		sys.sel.preloadMu.Lock()
+		ch := sys.sel.GetChar(int(numArg(l, 1)))
+		var anim *Animation
+		if ch != nil {
+			anim = ch.anims.get(int32(numArg(l, 2)), int32(numArg(l, 3)))
+		}
+		sys.sel.preloadMu.Unlock()
+		if anim != nil {
 			a := NewAnim(nil, "")
 			a.anim = anim
 			if !nilArg(l, 4) && !boolArg(l, 4) && a.anim.totaltime == a.anim.looptime {
@@ -1188,7 +1195,14 @@ func systemScriptInit(l *lua.LState) {
 		@treturn Anim|nil anim A new `Anim` userdata wrapping the preloaded animation,
 		  or `nil` if no matching animation exists.
 		function animGetPreloadedStageData(stageRef, group, number, keepLoop) end*/
-		if anim := sys.sel.GetStage(int(numArg(l, 1))).anims.get(int32(numArg(l, 2)), int32(numArg(l, 3))); anim != nil {
+		sys.sel.preloadMu.Lock()
+		st := sys.sel.GetStage(int(numArg(l, 1)))
+		var anim *Animation
+		if st != nil {
+			anim = st.anims.get(int32(numArg(l, 2)), int32(numArg(l, 3)))
+		}
+		sys.sel.preloadMu.Unlock()
+		if anim != nil {
 			a := NewAnim(nil, "")
 			a.anim = anim
 			if !nilArg(l, 4) && !boolArg(l, 4) && a.anim.totaltime == a.anim.looptime {
@@ -3397,6 +3411,18 @@ func systemScriptInit(l *lua.LState) {
 		l.Push(lua.LString(c.name))
 		return 1
 	})
+	luaRegister(l, "getCharPreloadStatus", func(l *lua.LState) int {
+		/*Query the background preload state of a character slot.
+		@function getCharPreloadStatus
+		@tparam int charRef 0-based character index in the select list.
+		@treturn string state Preload state: `"idle"`, `"queued"`, `"loading"`, `"ready"`, or `"error"`.
+		@treturn string err Error message (empty string if no error).
+		function getCharPreloadStatus(charRef) end*/
+		state, err := sys.sel.CharPreloadStatus(int(numArg(l, 1)))
+		l.Push(lua.LString(state.String()))
+		l.Push(lua.LString(err))
+		return 2
+	})
 	luaRegister(l, "getCharRandomPalette", func(*lua.LState) int {
 		/*Get a random valid palette number for a character slot.
 		@function getCharRandomPalette
@@ -4005,6 +4031,18 @@ func systemScriptInit(l *lua.LState) {
 		l.Push(lua.LNumber(sys.sel.selectedStageNo))
 		return 1
 	})
+	luaRegister(l, "getStagePreloadStatus", func(l *lua.LState) int {
+		/*Query the background preload state of a stage slot.
+		@function getStagePreloadStatus
+		@tparam int stageRef Stage index as used by the select system.
+		@treturn string state Preload state: `"idle"`, `"queued"`, `"loading"`, `"ready"`, or `"error"`.
+		@treturn string err Error message (empty string if no error).
+		function getStagePreloadStatus(stageRef) end*/
+		state, err := sys.sel.StagePreloadStatus(int(numArg(l, 1)))
+		l.Push(lua.LString(state.String()))
+		l.Push(lua.LString(err))
+		return 2
+	})
 	luaRegister(l, "getStageSelectParams", func(*lua.LState) int {
 		/*Get parsed select parameters for a stage entry.
 		@function getStageSelectParams
@@ -5443,6 +5481,14 @@ func systemScriptInit(l *lua.LState) {
 		l.Push(lua.LBool(sys.postMatchFlg))
 		return 1
 	})
+	luaRegister(l, "preloading", func(l *lua.LState) int {
+		/*Check whether resources are currently being preloaded.
+		@function preloading
+		@treturn boolean `true` if assets are still being preloaded.
+		function preloading() end*/
+		l.Push(lua.LBool(!sys.sel.AllPreloadsReady()))
+		return 1
+	})
 	luaRegister(l, "preloadListChar", func(*lua.LState) int {
 		/*Mark a character sprite or animation for preloading.
 		@function preloadListChar
@@ -5493,6 +5539,34 @@ func systemScriptInit(l *lua.LState) {
 		fmt.Println(strArg(l, 1))
 		return 0
 	})
+	luaRegister(l, "queueCharPreload", func(l *lua.LState) int {
+		/*Queue a character for background preloading of portraits and palettes.
+		@function queueCharPreload
+		@tparam int charRef 0-based character index in the select list.
+		@tparam[opt=1] int priority Priority level (`1` = low, `2` = high).
+		function queueCharPreload(charRef, priority) end*/
+		ref := int(numArg(l, 1))
+		priority := PreloadPriorityLow
+		if !nilArg(l, 2) {
+			priority = int(numArg(l, 2))
+		}
+		sys.sel.QueueCharPreload(ref, priority)
+		return 0
+	})
+	luaRegister(l, "queueStagePreload", func(l *lua.LState) int {
+		/*Queue a stage for background preloading of portraits.
+		@function queueStagePreload
+		@tparam int stageRef Stage index as used by the select system.
+		@tparam[opt=1] int priority Priority level (`1` = low, `2` = high).
+		function queueStagePreload(stageRef, priority) end*/
+		ref := int(numArg(l, 1))
+		priority := PreloadPriorityLow
+		if !nilArg(l, 2) {
+			priority = int(numArg(l, 2))
+		}
+		sys.sel.QueueStagePreload(ref, priority)
+		return 0
+	})
 	luaRegister(l, "rectDebug", func(*lua.LState) int {
 		/*Print a rectangle's debug information.
 		@function rectDebug