Tutorial: Creating awesome water with LiquidFun, snapshots, and filters

24 September 2015

Tutorial: Creating awesome water with LiquidFun, snapshots, and filters

This tutorial comes to you courtesy of Andreas von Lepel of Frozen Gun Studios. Following the worldwide success of “Freeze! – The Escape” (iOS/Android) with more than 11 million freemium downloads, Frozen Gun Studios has just released the sequel, “Freeze! 2 – Brothers” (iOS/Android), built entirely in Corona SDK and featuring LiquidFun-based water effects.

---

Overview

Very early in the development, I decided that it would be really interesting for the gameplay if I could have water and poisonous liquids like rocket fuel sloshing around in the rotating levels. Have a look at the trailer to see what we did:

As you can see, both our heroes can swim in the water, but in later stages the task for the player is to first collect all the deadly rocket fuel into a barrel and then to pick it up to open the level exit.

Project code

Setting up a scene with basic water using LiquidFun is really easy and there are some nice examples included in the Corona SampleCode repository. However, creating really nice, transparent water with a visible “surface” is a little harder and you need to use snapshots and filters. Fortunately, as usual with Corona SDK, even complex stuff is mostly done for you by the engine.

As we step through this tutorial, I encourage you to download the LiquidFun-Transparency project in the GitHub repository, also bundled into recent builds of Corona SDK:

CoronaSDK-XXXX → SampleCode → Physics → LiquidFun-Transparency

Within the project folder, open the main.lua file. We’ll start with the basic world setup:

Liquid “container”

In this block, I use three static rectangles to build a container outside of the screen boundaries. The container is open at the top and it will later hold the water inside of the screen.

Scrolling background

I want even demos to look nice, so in the next block, I add an endless scrolling background by placing two identical background images adjacent to each other, one fully visible in the middle of the screen, the other to the right of it.

Note that both images are moved slowly to the left and then, via endless iterations, are set back to their original positions and moved again, all using simple transition.to() calls.

The hero

Next, I add our eye hero into the scene as a dynamic physics object that will swim on the water. It can also be touched and dragged around by the user. I will not dive into the touch-drag code, about which a lot has been written and demonstrated previously.

LiquidFun particle system and water

In the next block, the particle system for the water is created, and a big rectangle of water particles is placed into the scene.

And this is the result if you start the code now:

The water is flowing, but it’s more like oil, because there is no transparency yet.

Adding transparency (first attempt)

Now things get a little more complex. I want to render the water semi-transparent, e.g. with an alpha value of 0.3 (30%) so that the background is visible through the water.

If I change the last value (alpha) of the the color property on line 111, there will be some transparency, but not exactly what I’m looking for:

Each particle now has an alpha value of 30%.If you look closely at the image, you can see that each round particle now has an alpha value of 0.3, and this gives a chaotic rendering of the water because all of the particles overlap slightly. While this could be nice effect for certain cases, it’s definitely not what I am trying to achieve.

Adding transparency using a snapshot

The solution is to render all the particles into a snapshot texture on each frame and then apply transparency to the entire texture. Here are the relevant lines:

Essentially, a snapshot and its group are created, positioned in the center of the content area. Note that the width and height of the snapshot are adjusted by the letterboxWidth and letterboxHeight variables calculated earlier in main.lua — this ensures that, when running in "letterbox" scale mode, the snapshot occupies the entire screen on devices of various aspect ratios.

On line 123, I set the alpha value of the entire snapshot to 0.3, effectively setting the entire snapshot texture to 30% opacity. Following this, the particle system is inserted into the snapshot group and finally, with the help of an "enterFrame" listener, the snapshot is invalidated and rendered anew each frame.

With this addition, you can see that the water now has realistic transparency:

Transparency! At last!

Go for pretty and add a filter

After I got this far, I was quite happy. But the cool engineers at Corona Labs added filter support, so I started to experiment a lot with all of the filters and filter options in my quest to add a nice visible surface to the water. It took some time to achieve the correct look, but in the end it was really easy:

And that’s it, we now have water with transparency and a nice water surface!

The water “surface” shows as a visible line on top of the water
(the edge of the rendered water enhanced by the sobel filter).

Where to go from here

From here, there are a lot of experiments you can do, e.g. play around with the density of the hero eye (with this you can influence whether it should be very light and always float on top of the water, or whether it should be heavy and sink below).

Another option is to use different filters for the water and tune their respective filter settings:

• snapshot.fill.effect = "filter.emboss"
• snapshot.fill.effect = "filter.frostedGlass"
• snapshot.fill.effect = "filter.crystallize"
• snapshot.fill.effect = "filter.scatter"

Finally, don’t forget the many different “flags” you can use for the LiquidFun group — e.g. add "staticPressure" and the water particles at the bottom of the container will not be compressed.

Performance issues

Not all devices are powerful enough to display water with these added special effects while maintaining an acceptable frame rate. Because of this, I take the following precautions:

• On iOS, I use the snapshot on all supported devices (iPhone 4S and better; iPad 2 and better). However, the additional sobel filter is added only on more powerful devices like the iPad Air or iPad mini 2 (iPad4,*), iPhone 5S (iPhone6,1), or iPod Touch 5G (iPod5,1) and better.
• For Android, I set the minSdkVersion to "16" (Android 4.1) to exclude many older devices. Also, I use the sobel filter only on devices that support high precision shaders, as determined by this:
  system.getInfo( "gpuSupportsHighPrecisionFragmentShaders" )
• Finally, I test the system.getInfo( "androidDisplayDensityName" ) for "xhdpi", "xxhdpi", and "xxxhdpi" — only these devices will get the sobel filter, because they are quite modern and should hopefully be fast enough.

Conclusion

As you can see, it is quite easy to create nice-looking water and other liquids, and at last the technology is good enough to make all of this useable on modern mobile devices. I’m looking forward to seeing more games which make use of this, as liquids are great fun for players and developers alike.

If you want to learn more about “Freeze! 2 – Brothers,” visit www.freeze2.com, or download it for either iOS or Android. I hope you enjoy the game!

---