---------------
Gameplay Notes:
---------------

- Media 'flows' from high to low elevations dynamically.
- Platforms rising out of media are given a temporary draining/waterfall visual effect.


---------------
Installation:
---------------

Select 'Dynamic_Water_v2_00.lua' under Preferences -> Environment -> Solo Script
Select 'WaterBuckets_v2_00.sceA' under Preferences -> Environment -> Map

I have only tested this script with the included Water Buckets V2 map. Your milage may vary, but I suggest using with maps specifically created with the custom script in mind.


---------------
Versioning: 
---------------

V2.00,  8 Dec 2025
-- Complete rewrite
-- Media may now traverse to polygons without pre-assigned media.
-- Sounds added when media flows onto dry polygons.
-- Platforms rising out of liquids will temporarily have pleasing draining/waterfall effects added.
-- Platforms can transport media volumes.

v1.22,  30 Sept 2013
-- Initial Public Release


---------------
Postmortem/Misc:
---------------

The original V1 dynamic media script was written back in 2013. At that time I was just becoming accustomed to Lua syntax, so the implementation was limited to some basic loops. https://www.pfhorums.com/viewtopic.php?f=22&t=36764

Around Sept. 2017, Chocolateer from the Pfhorums messaged me with their implementation that improved on a number of weaknesses of my script. For one, my script was naïve about mass conservation and distribution. If a media polygon had multiple neighbors, the first neighbor observed in a loop might take all available media allotment.  Chocolateer's script did a two-pass. First, ideal distributions were calculated for all neighbors. Then the results were equivalently divided down to the lowest allowable mass conservative value. Their script was also more careful to avoid accumulative rounding errors by tracking volume in Lua rather than continuously back-calculating from in-game heights. Chocolateer had mentioned wanting to polish their script before releasing, but as of 2025, I don't recall seeing it in the wild.

Anyways, I was going through all my old Aleph One stuff one-by-one to record example videos for my YouTube Aleph One creations playlist and figured it would be a good opportunity to revisit the concept using the insights of the newly released AI model Gemini 3.0 Pro.

It turns out, being able to create a new Media was added to Aleph One Lua suite in 2021. Hand-creating unique media for the polygons where flow would traverse was a major limitation of both my and Chocolateer's script. This new implementation heavily leverages that newer feature to expand the flow-range capabilities dramatically.

The script does the following:
1) The initial media volume per polygon is calculated. Lua tables absorb the responsibility of volume tracking. As such, Media slots are only used as a final visual representation of liquid height.
2) Every game tick, the script iterates through every wet polygon. It calculates flow based on height difference and shared line length between the source polygon and its neighbors. Similar to Chocolateer's approach, the script first calculates outflow distributions for all neighboring polygons, divides to ensure mass conservation, and finally, once all polygons are calculated, the flow distributions are executed.
3) Leveraging the 'New Media' function, the script manages a pool of created Media objects (Default: 64). Each wet polygon is assigned a unique height/media. Wet polygons with heights within 4/1024 WU are merged to use one media. If the number of unique heights is still greater than the pool of available media objects, then further clustering will occur based on closest weighted heights.

Overall, I think the results look pleasing. I especially like when platforms descend/ascend out of the media and the surrounding media heights ripple outwardly. 

You can probably think of all the limitations of the script, but the most impactful one is that media don't have textures on their sides. Therefore, there will be visual gaps between water heights. The software renderer is slightly better than the OpenGL renderer in this regard as the gaps will have smears rather than see-through vacancies - The smear tends to blend the surrounding water textures colors and be a less obvious dislocation.

Another limitation is the flow is somewhat slow-ish. I tried flow values greater than 0.5, but the simulation jitters and doesn't settle. It could probably be fixed with more sub-steps than 30hz, but I didn't want to go too far down that road.

Adding media flow based on the direction of the liquid transference looked extremely ugly. Each media has it's own texture offset due to it's flow, so the adjacent polygons did not have good texture continuity. Oh well.

No further plans to expand the script at this time. I think it would be cool for a map puzzle, maybe with timed water gates or something.


----
V1.22 is included in this download package for posterity.
Original Read-Me Below:

DynamicWater V1.22.lua

Marathon's media 'flows' from high elevations to low dynamically.
Please see the included 'Water Buckets.sceA' map as an example. [Punch the switches]


Some limitations of the script are as follows:


1. Media is limited to polygons defined during mapmaking. 

For flow to occur, the media's polygon edge must be adjacent to a polygon also containing media. 


2. Media shares properties [height, high, low tide] amongst all polygons it is placed.

This means that if two polygons have the same media defined, and the script changes the height of one polygon's media, the other polygon's media height changes to the same value.
Mappers need to put unique media in adjacent polygons to create the pseudo-flow.  


3. Media exists under polygons.

For moving platforms, media may not ride the moving floor as it realistically would. Platforms cover up the media without displacing it.
For the best look, mappers need to set the media of platform polygons to the highest adjacent media source.


4. Media goes 'missing' while flowing.

Media may be hidden under floors based on the media tides and moving dam platforms. 
Setting the script's k value lower may prevent lost mass as the expense of longer liquid level equalization times. 


---------------
Credits:
---------------

Author: Zott and Gemini 3.0 Pro
Special thanks to Chocolateer from The Pfhorums for inspirational improvements.

Feel free to modify and include in your own works.
Attribution appreciated but not required.
