black flash when switching gamestates (hump)

[DPS2004]

Hello

I was working on the main menu for my game, when I noticed that the screen flashes black whenever the gamestate switches. I can't see to find any reason for this!

Steps to reproduce:

Launch main.lua
Select "play" with spacebar
press left arrow key to move cursor to "assault"
Press space to launch Assault gamemode
as the state switches to assault.lua, notice the black flash

Any help would be appreciated.

[pgimeno]

I added a print to menu.update, menu.draw, assault.update and assault.draw, and this happened:

Code: Select all

...
menu.update
menu.draw
menu.update
menu.draw
menu.update
assault.update
assault.draw
assault.update
assault.draw
...

Notice the lack of a menu.draw or assault.draw call between the last menu.update and the first assault.update. So I dug into the hump gamestate lib and found this:

Code: Select all

	-- call function only if at least one 'update' was called beforehand
	-- (see issue #46)
	if not state_is_dirty or func == 'update' then
		...

Here's issue #46:

https://github.com/vrld/hump/issues/46

Apparently this behaviour is intentional, but it is breaking your workflow because draw is not called for 1 frame. Sounds like a cure worse than the disease.

That said, switching gamestates is a delicate operation, as karai17 and shakesoda mention in the issue. If you run the state switch in state1.update and the next thing that executes is state2.draw, then you have the situation that state2.update was never executed before state2.draw, and that can lead to bugs.

How to solve that in a way that doesn't have this problem? Well, I see two possible solutions. One is to retrigger the update event in the new state, but then you need to know whether the state change happened within the update event, to be sure that's the correct thing to do. The other is to defer the state switch, including the call to the leave event, until the current frame completes. This can be done by patching love.run (which is very LÖVE-version dependent) or in a more compatible but uglier way, by patching the last function called every frame: love.graphics.present.

[DPS2004]

How would I do the second thing with the patching and love.graphics.present?

[pgimeno]

After more thought, I think that using Löve's event queue is easier and cleaner than patching love.graphics.present, because it will better keep track of all gamestate stack operations. It unfortunately brings a few limitations.

Here's the modified gamestate.lua:

Code: Select all

--[[
Copyright (c) 2010-2013 Matthias Richter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

Except as contained in this notice, the name(s) of the above copyright holders
shall not be used in advertising or otherwise to promote the sale, use or
other dealings in this Software without prior written authorization.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

(c) Copyright 2020 Pedro Gimeno Fortea

Permissions to use, to copy, to modify and to distribute this software for any
purpose are hereby granted, provided that the above copyright notice and this
permission notice appear in all copies. This software comes with no implied
warranty.

]]--

local function __NULL__() end

 -- default gamestate produces error on every callback
local state_init = setmetatable({leave = __NULL__},
		{__index = function() error("Gamestate not initialized. Use Gamestate.switch()") end})
local stack = {state_init}
local initialized_states = setmetatable({}, {__mode = "k"})
local state_to_key = setmetatable({}, {__mode = "k"})
local key_to_state = setmetatable({}, {__mode = "v"})

local GS = {}
function GS.new(t) return t or {} end -- constructor - deprecated!

local function change_state(stack_offset, to, ...)
	local pre = stack[#stack]

	-- initialize only on first call
	if not initialized_states[to] then
		initialized_states[to] = true
		;(to.init or __NULL__)(to)
	end

	stack[#stack+stack_offset] = to
	return (to.enter or __NULL__)(to, pre, ...)
end

function love.handlers.gsswitch(to, ...)
	to = key_to_state[to]
	;(stack[#stack].leave or __NULL__)(stack[#stack])
	return change_state(0, to, ...)
end

function love.handlers.gspush(to, ...)
	to = key_to_state[to]
	return change_state(1, to, ...)
end

function love.handlers.gspop(...)
	assert(#stack > 1, "No more states to pop!")
	local pre, to = stack[#stack], stack[#stack-1]
	stack[#stack] = nil
	;(pre.leave or __NULL__)(pre)
	return (to.resume or __NULL__)(to, pre, ...)
end

function GS.switch(to, ...)
	assert(to, "Missing argument: Gamestate to switch to")
	assert(to ~= GS, "Can't call switch with colon operator")
	local k = state_to_key[to]
	if not k then
		k = tostring(to)
		state_to_key[to] = k
		key_to_state[k] = to
	end
	love.event.push("gsswitch", k, ...)
end

function GS.push(to, ...)
	assert(to, "Missing argument: Gamestate to switch to")
	assert(to ~= GS, "Can't call push with colon operator")
	local k = state_to_key[to]
	if not k then
		k = tostring(to)
		state_to_key[to] = k
		key_to_state[k] = to
	end
	love.event.push("gspush", k, ...)
end

function GS.pop(...)
	love.event.push("gspop", ...)
end

function GS.current()
	return stack[#stack]
end

-- XXX: don't overwrite love.errorhandler by default:
--      this callback is different than the other callbacks
--      (see http://love2d.org/wiki/love.errorhandler)
--      overwriting thi callback can result in random crashes (issue #95)
local all_callbacks = { 'draw', 'update' }

-- fetch event callbacks from love.handlers
for k in pairs(love.handlers) do
	all_callbacks[#all_callbacks+1] = k
end

function GS.registerEvents(callbacks)
	local registry = {}
	callbacks = callbacks or all_callbacks
	for _, f in ipairs(callbacks) do
		registry[f] = love[f] or __NULL__
		love[f] = function(...)
			registry[f](...)
			return GS[f](...)
		end
	end
end

-- forward any undefined functions
setmetatable(GS, {__index = function(_, func)
	return function(...)
		return (stack[#stack][func] or __NULL__)(stack[#stack], ...)
	end
end})

return GS

This is the result with the above:

Code: Select all

...
menu.update
menu.draw
menu.update
menu.draw
assault.update
assault.draw
assault.update
assault.draw
...

Note that the state switch command is issued in the last menu.update, but menu.draw is still called and the state switch is effective immediately afterwards, including all associated side effects (the leave, enter, resume callbacks will be called at that point).

A caveat with the modified gamestate.lua is that it does not support passing tables that contain functions, as arguments for enter or resume, which means you can't pass objects, for instance. You can only pass the same kind of values that you can send through love.thread channels. And of course, you can't change states from a thread.

[DPS2004]

Thank you so much for the help!

[zorg]

After more thought, I think that using Löve's event queue is easier and cleaner than patching love.graphics.present, because it will better keep track of all gamestate stack operations. It unfortunately brings a few limitations.

(...)

A caveat with the modified gamestate.lua is that it does not support passing tables that contain functions, as arguments for enter or resume, which means you can't pass objects, for instance. You can only pass the same kind of values that you can send through love.thread channels. And of course, you can't change states from a thread.

Just wanted to add, that technically, you could dump specific functions with string.dump, and pass those, then loadstring them... but it's about the opposite of what i'd call a decent practice.

What you could do is keep a "jumptable" around, with numbers (or strings) as keys and functions as values, and just pass the keys; that'd work.

[pgimeno]

Just wanted to add, that technically, you could dump specific functions with string.dump, and pass those, then loadstring them... but it's about the opposite of what i'd call a decent practice.

It's not just about good/bad practice; it's also that it breaks reasonable user expectations. If you want to pass an object, you don't expect to receive a copy of the object, but the original object. However that mechanism would create a copy.

Edit: And that's without taking into account the upvalues in the closures, which add extra complications.

What you could do is keep a "jumptable" around, with numbers (or strings) as keys and functions as values, and just pass the keys; that'd work.

My mod is doing something like that already, by using a weak table for storage, and mapping states (which it assumes to be tables with functions) to their tostring() representation, and passing that around instead of the state itself.

IIUC the event system is designed to work across threads (e.g. you should be able to issue love.event.quit() from any thread). However, for this use case, that's overkill and counter-productive, due to the fact that the original object is not being passed around, so one solution would be to use the weak table mechanism to pass a packed version of the parameters.

It's not that it can't be done, it's that it's quite some work to put something together to allow passing around that kind of stuff, and it's not worth doing if there's no real demand. I have never needed passing object parameters when switching states.

Edit: The most common use case for passing parameters to the new state is probably something like a pause menu in a puzzle game, with an option to resume and an option to restart. Both would resume the state, but the restart option would also force a reinitialization of the level. A string suffices in that case.

[laincake0]

What about creating a global state_args table to put the arguments given to enter function? Then event handler can call GS.push(state, unpack(state_args)). That way I can pass functions and objects to the enter function. Would this be good practice?