the agonizing part about trying to do anything off the beaten path in an especially novice-friendly engine is that no matter how you try to phrase your task, the search results are going to be ten thousand copies of people asking extremely basic questions like "how do you hide the textbox"
and then if you try to ask in support channels you have to fight against a current where they assume you're really just asking how to hide the textbox, and if they're not an engine dev then chances are they actually don't know how to do more than hide the textbox
anyway i had some adventures today
there is so much stuff in that engine, including several of its own DSLs, multiple animation systems, a parser library, and compatibility going back fucking forever. it's got a lot of documentation but it's also impossible to document fully. i don't know what "fully" would even mean.
the upshot is that unless you extremely know what you're doing at all times (or extremely don't know what you're doing and just do really basic stuff), it is really easy to make really weird fiddly annoying little fuckin things happen. little gremlins in your game
today i had a thing where a single small part of the dialogue box would flicker on every new passage. just for like one frame, like it was rendering slightly wrong but then worked itself out one frame later. and that is the kind of thing that irritates the piss out of me in my own work. it's jarring and ugly and feels like it makes me look like i do not know what i am doing
and after exploring multiple possible causes, including "this might be a bug in renpy"¹, i discovered that this was a result of my own attempt to use some shorthand in an ATL block.
i'm not going to dive entirely into this but the gist is that you can animate display properties by doing stuff like this:
transform hover_fade:
alpha 0.25
on hover:
linear 0.1 alpha 1
on idle:
linear 0.1 alpha 0.25
where the linear bit is an easing function to make the change happen over time. but i didn't want an animation in this instance, so i figured i would avoid repeating myself with the initial line:
transform hover_peek_up:
on hover:
yoffset 12
on idle:
yoffset 16
because it starts out idle, and this sets the properties instantly, so it should just do the on idle stuff right away and everything should be fine.
reader it was not fine. turns out everything starts out in a start state for, i guess, one frame, and the states are exclusive, so the yoffset would remain at its default of zero for that first frame.
and i didn't notice this at first because i didn't run through the script while i was putting the UI together; i just let renpy reload on the same line. so the flicker seemed like a new thing that started later on!
and this is just the kind of thicket i bumble into all the time. it's not like there's a State Examiner. these things are even called "events" in the documentation, which implies various properties, only most of which are correct. you can't even reliably debug print in a lot of places, because renpy peeks into the future to start loading images before they actually need to appear.
so no one with only a surface-level understanding of renpy could possibly diagnose this entirely self-inflicted problem. if you just copy/pasted and modified examples you would never even think to write something like i did. but someone who's been programming for a while might have DRY brain and try something like this. and now it'll rattle around in my head forever as a new particular pothole to steer around.
also the solution is on idle, start so it fires for both. don't know of a way to avoid repeating yourself with the alpha one though
¹ young programmers, heed my words: it is never a bug in the platform.
well ok. when you're starting out, there can be a tendency to think that "my code isn't doing what i think it should" means "there's a bug in the computer". and usually it isn't, especially if you haven't yet learned how to accurately transcribe your desires as code. however, if you do this long enough, you will run into genuine bugs in the platform, and you'll get a sense for what they feel like: rare (relative to the popularity of the platform), often bizarre, maybe a result of specific unusual circumstances that explain why no one else has seen it before. anyway i'm telling you this to stress that i would not reach for "this might be a bug in renpy" unless some "boy this is real fuckin weird" alarms were going off