I'm trying to make a mechanic where the players must push around a ball to act as their light source, and if they stand in the dark for an extended period of time they begin to take damage. Specifically, I'm looking for a four-second grace period while in the dark before the player loses 10 hit points per second. I know the gradual damage mechanic is possible, but has it been applied to distance from a light source before? Also, I may be able to work around this by ignoring the light source entirely, and just having damage received once the player exits the ball's radius. Thanks in advance!
I know of no API that lets you determine how lit up an area is, so distance from the nearest light source definitely sounds like the way to go.
If you have lit up areas other than that ball, don't forget to consider them too - either use Touched events with invisible parts (letting you know when they enter a "safe" zone) or have functions that determine whether they're in a lit-up area or not (based on their coordinate).
For implementing the grace period:
Every 'wait()' (you can do less frequent if you want), check to see if a player is inside a safe zone, near the ball, or in darkness. If they're safe, reset their grace-period time (or return it gradually, your choice). If they're not safe and the grace-period has run out, start giving them damage based on how much time has elapsed since the last update. Otherwise, reduce the grace-period they have left by the elapsed time.