_wateralpha and other worldspawn keys proposal

[ericw]

Wateralpha as a worldspawn key has been proposed before, e.g. http://forums.inside3d.com/viewtopic.php?f=3&t=2515 , but didn’t reach any consensus.

Recently another discussion started in the Quakespasm thread on func_, a few people asked for r_slimealpha/r_lavaalpha/r_telealpha cvars, and Preach and Lunaran chimed in requesting worldspawn keys: http://celephais.net/board/view_thread. ... &start=937

I think metl posted a really nice concept of how this could work here: http://celephais.net/board/view_thread. ... &start=971 . I implemented a prototype of this in Quakespasm (code and exe at the bottom), and tried to expand this into a proposal which I'm posting here.

So, the motivation is, the current possibilities for q1 mappers to control water alpha are pretty bad:

• put an “r_wateralpha” setting in quake.rc bundled with your map directory (e.g. the map jams do this)
  • pros: pretty reliable
  • cons: too global - gives all maps in a mod get the same setting. treatment of lava/teleporter/slime depends on engine
• use trigger_command to change r_wateralpha:
  • pros: can set different wateralpha for different areas
  • cons: requires custom qc, not saved in savegames, may be saved to config.cfg, will persist to next map, no control over how it applies to lava/teleporter/slime, generally the most dirty method possible
• use a func_illusionary on the water surface with an explicit "alpha" key on the entity. Haven't used this method, but it sounds cumbersome and I think the water transparency from the inside looking out will depend on r_wateralpha, not the func_illusionary alpha

What would be ideal is the situation in q3 mapping where you just provide an alpha channel in the texture or set a constant alpha value in the shader script. (i’ve not actually mapped for q3 but this is my understanding). Short of that, I think parsing worldspawn keys like is done for “fog”/“sky” is the next best thing.

Here are the worldspawn keys i’m proposing:

_wateralpha

• When a map is loaded, if the “_wateralpha” key is set in worldspawn, the given value should be used by the renderer instead of r_wateralpha for the duration of the map.
• Loading a map with this key shouldn’t have any other side effects; the value of the r_wateralpha cvar shouldn’t be modified*, and the value given in the worldspawn key shouldn’t persist in any way when you change to another map or disconnect EDIT: (*- or if the implementation modifies r_wateralpha when parsing the _wateralpha key, r_wateralpha should be reset to its original value when leaving the map, unless the player explicitly changes r_wateralpha)
• If the player (or qc code) changes the “r_wateralpha” cvar while the map is running, the engine may switch to using that value until the map is reloaded, or may continue using the value from worldspawn. (EDIT: Made optional at request of LordHavoc)
• EDIT: just to be clear, the value is a float from 0 (fully transparent) to 1 (fully opaque).

_slimealpha, _lavaalpha, _telealpha

• Follow the same rules as “_wateralpha”, but these worldspawn keys apply to a subset of water textures:
  
  _slimealpha applies to textures beginning with “*slime”
  _lavaalpha applies to textures beginning with “*lava”
  _telealpha applies to textures beginning with “*tele”
  
  (same naming patterns in RMQEngine).
• It should be possible to implement this behaviour regardless of whether an engine already has special treatment for slime/lava/tele textures or not (RMQEngine, DirectQ have r_slimealpha/lavaalpha/telealpha cvars, Fitzquake Mark V, automatically makes “*tele” textures opaque, I think). If a specific _slimealpha/_lavaalpha/_telealpha worldspawn key isn’t provided, the engine would just do whatever its default behaviour was for those textures.

_skyfog

• r_skyfog is a fitzquake cvar that controls the fog opacity against the sky. 0 means there is no fog drawn over the sky/skybox, 1 means the sky is drawn as the fog color, fully opaque.
• it's not directly related to the water alpha settings, but the spirit is the same: in a more sophisticated map format, this would be a property of the sky texture or map entity. In Fitz 0.85, it's a cvar, which is better than nothing, but the mapper can't really make use of it without resorting to r_wateralpha-like hacks.
• including it in this proposal because mfx requested it, and it was easy to implement using the same technique as _wateralpha. It's only relevant for fitz-derived engines or engines that implement sky fog.

—

That's all, comments / feedback would be appreciated.

Rationale for underscores in the keys: Preach says: “The intent here was to make it so that it doesn't throw up errors in engines that don't support the key, since they're already trained to ignore it : - ). I know the original intent was for tools, but it can serve a second purpose for things the engine understands but is hiding from the QC and third for hiding QC fields from those pesky mappers ” (EDIT: Engines should accept _wateralpha or wateralpha, same for the other keys)

--
ADDED: Test maps, with readme and screenshots:
http://www.quaketastic.com/files/misc/w ... stmaps.zip

UPDATED: Diff for my initial stab at implementing this:
https://github.com/ericwa/Quakespasm/co ... a?expand=1

UPDATED: Quakespasm win32 binary with the patch:
http://quakespasm.ericwa.com/job/quakes ... c015d1.zip

There are a couple known bugs with my implementation:

• FIXED specifying 0 for the _lavaalpha/_telealpha/_slimealpha worldspawn keys doesn't actually cause the alpha to be set to 0 for those textures, but means "fall back to the wateralpha value".
• FIXED if you, as a player, want to override the _wateralpha worldspawn key, you have to set the r_wateralpha cvar to something other than it's current value. e.g. worldspawn _wateralpha is 0.5, r_wateralpha is 1. If you want to override the alpha to be 1, you have to do "r_wateralpha 0.9" then "r_wateralpha 1"

[Baker]

Ah, I knew this day would come.

And I'm not sure what to say.

This kind of discussion came up a couple of years ago and the main thought is that it could lead to infinite worldspawn keys.

[When possibly the real problem is that engines can't detect if the map are vised for transparent water or not.]

I'm not really sure what to think, the problem is real. Doesn't fix this for any of the thousands of existing maps

[leileilol]

All 3 are also possible to implement in Engoo (software renderer engine). I would have to change the water drawing code to point to different calculated translation tables (generated on map load) depending on content. Skyfog is even doable very easily by applying a color blend to the sky texture itself on load without any additional rendering code.

[Spike]

> If the player changes the “r_wateralpha” cvar while the map is running, the engine should switch to using that value until the map is reloaded. This allows for interactive tweaking by a mapper, or lets the player override the value if they don't like the mapper's choice.

the way you implemented that makes me uneasy.
it depends upon other engines having callbacks for when a cvar was modified. it seems clumsy.
its also lots of extra functions. I don't like lots of extra functions, even if they're just one line long. seems messy.

> specifying 0 for the _lavaalpha/_telealpha/_slimealpha worldspawn keys doesn't actually cause the alpha to be set to 0 for those textures, but means "fall back to the wateralpha value".

this is dangerous. use -1 to flag it as unspecified if needed. you may even want to avoid using a float to flag it active/inactive. a bitfield instead or something.


one question: what about 'pretty water' stuff, with a global enable that enables both reflection and refraction (the warpy transparenty view). in this case you don't want to be drawing some ugly water surface over the top, ruining the effect.
which feature wins?


needs a test-case, because I'm too lazy to make maps myself.



@baker
.ent files.
detecting watervis won't help you if the water is meant to be 20% visible on one map and 60% on annother, nor if the use has the cvar set to 1 because vanilla water was never meant to be transparent (and they can't be arsed to delete their vis patches).
of course, you can't have one brush with one translucency and another with a different setting with this, unless of course if you make one slime and another a teleporter, but that just gets really messy.
but you know someone is going to do it anyway...

[Baker]

detecting watervis won't help you if the water is meant to be 20% visible on one map and 60% on annother, nor if the use has the cvar set to 1 because vanilla water was never meant to be transparent (and they can't be arsed to delete their vis patches).
of course, you can't have one brush with one translucency and another with a different setting with this, unless of course if you make one slime and another a teleporter, but that just gets really messy.
but you know someone is going to do it anyway...

I've seen plenty of maps that weren't intended for r_wateralpha and if you use it is "all wrong". Something Wicked is a good example, it has animated brush texture waterfalls which are, of course, solid --- and if the water is transparent it looks real bad.

Automatic underwater transparency detection: I forgot about this: http://forums.inside3d.com/viewtopic.php?p=9723 ... good stuff.

I completely forgot about that, probably because back then I was working on ProQuake and in multiplayer, I just used r_novis 1 and r_wateralpha 0.3 when playing online, so whether or not a map supported it or not, I had transparent water.

[mankrip]

I'll read this thread in full later, but for now I just want to reinforce this point:

read these fields as strings, to make sure that a value of zero is possible, since "0" != "". If the string is null, the cvar should be left unchanged.

By doing that, you do not even need engine support for the field from worldspawn; you can just stuffcmd the field value from the worldspawn entity directly into the cvar without having to worry about any special case. This approach is fully compatible with any engine.

For closed-source mods, this is simple to implement in the engine, and for open-source mods, it's even simpler to implement in the QC code. It's a case where modders don't need to wait for engine coders to agree on a standard.

[leileilol]

but stuffcmd isn't saved

It would suck if you die in a level, reload, and see the water get opaque and the fog disappear


Also I believe _keys should override the cvar when available, and not actually change the cvar itself.

[qbism]

Per texture in a vanilla-compatible texture name... Somehow...
*water-hey-I-am-35-percent
*water-some-other-muddy-water-yo-70-percent

[leileilol]

or you could shoehorn in a hexadecimal at the end followed by some symbol.

[ericw]

@Spike,

> If the player changes the “r_wateralpha” cvar while the map is running, the engine should switch to using that value until the map is reloaded. This allows for interactive tweaking by a mapper, or lets the player override the value if they don't like the mapper's choice.

the way you implemented that makes me uneasy.
it depends upon other engines having callbacks for when a cvar was modified. it seems clumsy.
its also lots of extra functions. I don't like lots of extra functions, even if they're just one line long. seems messy.

yeah, I agree having a side effect to changing a Cvar is sort of ugly.
just want to mention that the core part of the proposal is the meaning of the keys and the idea that the worldspawn keys, if present, should take precedence over cvars. The other bits, like how the player can override the worldspawn setting, don't necessarily need to be done the same way in every engine, although obviously it's nicer if they are.

Another possible mechanism for letting the player override the map value could be to have commands: map_wateralpha, map_lavaalpha, ..., map_skyfog
these return the current setting (whether from worldspawn or the corresponding cvar), and if you run the command with an argument, it updates the value used by the renderer until map reload (but doesn't touch the cvar).
the cvar callbacks would be removed so there's no more magic behaviour when changing the cvars. so the cvars would be strictly "the fallback value if the map doesn't specify this."

I'd say this version is less hacky / more logical, but requires players to learn a new command.

> specifying 0 for the _lavaalpha/_telealpha/_slimealpha worldspawn keys doesn't actually cause the alpha to be set to 0 for those textures, but means "fall back to the wateralpha value".

this is dangerous. use -1 to flag it as unspecified if needed. you may even want to avoid using a float to flag it active/inactive. a bitfield instead or something.

yeah, good point. even though my first draft implementation messes this up, I was intending _wateralpha/_lavaalpha/_telealpha/_slimealpha = 0 to mean fully transparent. will update the first post to mention that.

one question: what about 'pretty water' stuff, with a global enable that enables both reflection and refraction (the warpy transparenty view). in this case you don't want to be drawing some ugly water surface over the top, ruining the effect.
which feature wins?

I'd say the pretty water wins. I'm not sure how pretty water normally interacts with r_wateralpha, I should look at some examples of pretty water I guess.
OTOH, if there's just an external tga texture for "*water01" or whatever, the _wateralpha setting should still apply.

needs a test-case, because I'm too lazy to make maps myself.

good point, i will do that

[ericw]

detecting watervis won't help you if the water is meant to be 20% visible on one map and 60% on annother, nor if the use has the cvar set to 1 because vanilla water was never meant to be transparent (and they can't be arsed to delete their vis patches).
of course, you can't have one brush with one translucency and another with a different setting with this, unless of course if you make one slime and another a teleporter, but that just gets really messy.
but you know someone is going to do it anyway...

I've seen plenty of maps that weren't intended for r_wateralpha and if you use it is "all wrong". Something Wicked is a good example, it has animated brush texture waterfalls which are, of course, solid --- and if the water is transparent it looks real bad.

Automatic underwater transparency detection: I forgot about this: http://forums.inside3d.com/viewtopic.php?p=9723 ... good stuff.

I completely forgot about that, probably because back then I was working on ProQuake and in multiplayer, I just used r_novis 1 and r_wateralpha 0.3 when playing online, so whether or not a map supported it or not, I had transparent water.

no objections here. Just want to point out, imo "Automatic underwater transparency detection" is an orthogonal thing that could be implemented in an engine and not conflict with this proposal. that's about detecting maps not vised with transparent water, and forcing rendering as opaque even if the player's r_wateralpha is < 1. whereas this is about letting the mapper provide exact values tuned to get the visuals they want.

[ericw]

Per texture in a vanilla-compatible texture name... Somehow...
*water-hey-I-am-35-percent
*water-some-other-muddy-water-yo-70-percent

yes that's a possibility. i'd tend to prefer the worldspawn key idea, though, even though encoding the alpha value in the texture name is more powerful.

• more painful for mapper to make small adjustments to alpha (have to find/replace texture names across the map, and rename the texture in the wad - not fun)
• if the mapper wants to be explicit about alpha, it means renaming all existing water textures they want to use, vs. just adding a few keys to worldspawn.
• I feel the worldspawn key fits better into the existing ecosystem. it's the sort of thing a map author could easily edit into an old bsp and re-release, or people could put the worldspawn keys in .ent files for existing maps

[Baker]

people could put the worldspawn keys in .ent files for existing maps

Additive .ent files I hope, don't need a 35kb file each for 2000 maps when a couple lines will do.

[mankrip]

but stuffcmd isn't saved

It would suck if you die in a level, reload, and see the water get opaque and the fog disappear

Wrong.

Code: Select all

float JUSTLOADED = 0;
float NOTLOADED = 1;
.float savegame_status__;

Check every frame for self.savegame_status__. If it's JUSTLOADED, then run the stuffcmds and set it to NOTLOADED.

This way, (self.savegame_status__ == JUSTLOADED) will only happen when you load a savegame, or right after connecting to the server.

I talk with experience, I've worked on all kinds of savegame features through QC in my JoyMenu mod. This feature has already been implemented in it for over ten years, I've exhaustively researched and tested it, and it works perfectly.

Also I believe _keys should override the cvar when available, and not actually change the cvar itself.

Agreed, but this is not possible in vanilla GLQuake. The QC approach would be only for engines that doesn't support the custom worldspawn fields required.

So, what I'm saying is that both approaches should be done. One in QC, and one in the engine, both following the same standards. This way, mappers should be able to use this feature everywhere.

[qbism]

per-texture exceptions in worldspawn-
wateralpha 0.33
slimealpha 0.50
lavaalpha 1.00
texalpha *watermud 0.66