Sounds reasonable. Do you have any suggestion for the API in case it's not obvious from how this would be implemented?

Sounds reasonable. Do you have any suggestion for the API in case it's not obvious from how this would be implemented?

I wouldn't known. However I think that the intesity of the effect can be changed because it appears to be stronger the further down you go.

Shared functions:

-- Server
setUnderwaterEffectEnabled(element thePlayer, bool state)
setUnderwaterEffectStrength(element thePlayer, int strength) -- strength: 0-255

-- Client
setUnderwaterEffectEnabled(bool state)
setUnderwaterEffectStrength(int strength) -- strength: 0-255

If the underwater effect is disabled using setUnderwaterEffectEnabled, should using setUnderwaterEffectStrength re-enable it?

What if we just let 0 be disabled? (Assuming it actually has the same effect as being disabled.)

I agree.

I think we should also add a new function isPlayerUnderwater - imagine a scenario where you wanted the opposite effect (underwater effect when player is out of the water, and no effect when they're under the water) - I'll create a separate issue/PR for that.

There is an isElementInWater function but I doubt that lets you know if they're under the water, and I can't think of another way to detect this (with current Lua functions/methods).

Would this work? (untested)

-- Client side only
function isPlayerUnderwater(p)
    if not p.inWater then
        return false
    end
    local level = getWaterLevel(p.position)
    if not level then
        return false -- not close enough to the player
    end
    return p.position.z < level
end

Further to my last message, we can't simply let 0 be disabled.

Scenario:

Player is out of the water, you set the strength to 255 for a brief period, then back to 0 to stop the effect. Now the effect is completely disabled, and it won't happen when you get back under the water.

@qaisjp I'd imagine it'd be based on the player's camera being under the water, rather than the player itself. (aside from that it seems like it should work)

However come to think of it, your solution does satisfy the function name (isPlayerUnderwater) - so maybe we'd need two functions? (it could be useful to have these built into MTA and allow them to be shared between client and server).

Ok lets discuss this on the other issue, there's more edge cases than I realised

The screen also gets dark when the camera moves under water, if we add "setUnderwaterEffectEnabled" we should add this parameter aswell, not just the screen distortion.
A while ago i wanted to create an underwater world but it was literally not possible because the screen always gets dark.

If that's the case we would add the parameters to setUnderwaterEffectStrength e.g:

setUnderwaterEffectStrength(int distortionStrength, int darkenStrength) --all values 0-255