Google Summer of Code 2021 Work Product for Catrobat — Documentation

During the past 10 weeks in Google Summer of Code, as a student developer, I worked with International Catrobat Association - in their Android project — Catroid. Catroid is a mobile IDE for Android that utilizes its own visual scripting language to build applications and games without the knowledge of any kind of programming language or coding!

About Project

My GSoC project was aimed at introducing Particle Effects in Catroid, which will enable users to add various kinds of particle effects in their games including particles, glowing effects, fire, smoke, etc. The user should be able to add particles and control other parameters like particle color, particle size, etc.

Project description

The Project was divided into different phases.

1. The first step was to develop a way to incorporate particle effects into the game lifecycle such that users can control the particle state while the particles regularly update themselves in the background.
2. the second step was to create the fade_particle_effect_brick that will trigger the fading in and fading out of the particles.
3. the third step was to create a set_particle_color_brick that will control the color of the particles in-game, (users will be able to slowly change particle color at any point in time)
4. the fourth step and future scope of the development phase were to use the added particle effects to create cool effects like fire, smoke, etc that could be added to the game.

this broad generalization was helpful but proved to be much more difficult as we dived into the development phase, many new changes had to be made to make the particle effect work perfectly well and as desired by the project members and users.

Getting Started

Before we dive into the project, it’s important that we talk about particles a bit more. A particle system simulates and renders many small images (or Meshes), called particles, to produce a visual effect. Each particle in a system represents an individual graphical element in the effect. The system simulates every particle collectively to create the impression of the complete effect. Games achieve fire, smoke, glowing graphics, and other foggy effects using particle systems! An example of a particle system is shown below.

To get started with incorporating Particle Effects in Catrobat, I used LibGDX. libGDX is a cross-platform Java game development framework based on OpenGL (ES) that works on Windows, Linux, macOS, Web, Android, and iOS. It is a pretty cool library that enables you to create simple to heavy games with just a little bit of code! I highly recommend you to check it out if you are interested in developing cross-platform games (or Game IDEs) using Java.

Now as we have a proper working library it might seem the road ahead is easy — we just have to call the provided functions, but unfortunately, that is not the case. There’s a long list of parameters that we have to define before we can even set up a proper working particle system! We will talk about this problem in detail in the next section.

Now as we have a library that supports particle effects and we have a set of parameters with which we can create a working model of the particle effect, I had to think of a way to incorporate this particle effect into the visual scripting language of Catrobat and its scene lifecycle. We will talk about how this was a problem and how I solved it in the later sections.

Now after we’ve incorporated the particle effects, other parts become quite clear. I could use the same process I used to add the particle effects to change its color, update other parameters, or even add special effects like smoke, fire, etc.

Development Journey

Pre-processing: simulate particle effects

Fortunately for me, Catroid already supported LibGDX, so that solved some problems. but as discussed earlier, There are a lot of parameters that are required to be set up to create a working model of a proper particle system. There’s — particle size, particle color, particle shape, gravity, wind speed, particle velocity, opacity, and dozens of such parameters. It might overwhelm the developer to even set up a single working particle system! To combat this LibGDX provides you with a free GUI tool called the particle editor, which can be used to create a base template for the particles.

it provides you with switches, scroll tabs, and controls that can be tweaked to your liking. Once you are satisfied with the particle effect you can click save to export a base file that could be used as a starting template for the particle system in your apps or games. You just have to import this base file every time you have to generate a similar effect and not specify the parameters individually. LibGDX requires this base file whenever you want to generate a particle system.

First Step: Introduce the particle Effect in Catrobat

This is the most important step. We have to introduce this particle effect in Catroid so that users can generate particles whenever they encounter the particles brick in the Visual Scripting Language. Catroid uses a set of visual blocks instead of pieces of code. proper arrangement of these visual blocks is converted to underlying code to create many different kinds of games. using this method even non-programmers, students and beginners can create creative and innovative games.

This step can further be divided into further substeps:

1. introduce particle system in Catroid.
2. create a ‘brick’ that triggers the fading in and fading out of particles.
3. connect the brick with the particle system.

The FadeParticleEffect brick was developed that will hold 2 options fade in and fade out. under the hood, the brick calls the particle emitter of LibGDX and fades in or out the particle effect depending on the option chosen by the user. FadeParticleEffect Brick and FadeParticleEffectAction had to be created for this purpose and had to be connected with the catroid workflow

Fade Particle Brick

proper unit and UI tests as well as Catrobat Language tests were also added to ensure proper working of the bricks.

While connecting the brick with particles I also had to take care that the particles inherit the sprite properties, for example particle spawn area must be bigger for bigger sprites and smaller for smaller sprites. Likewise the particle effects must also be inherited by sprite ‘clones’. I had to ensure that the particles are not generated before or too late after the FadeParticleBrick was encountered. It must also work properly with existing property bricks!

This is the PR with the completed changes and updates: https://github.com/Catrobat/Catroid/pull/4216

Roadblock

While adding the fade effect we encountered a bottleneck issue. To achieve a proper particle effect like the one shown above (brighter core and darker edges) the particles must not be opaque and have an “additive effect” this is enabled by default. This looks very realistic, but the problem with this setup is the fact that the effect is not visible clearly in lighter backgrounds (so much so that it is literally invisible in white backgrounds) to counteract this effect and provide a better user experience a condition was added to check whether the scene has any background at the start, if it doesn’t (ie. the background is white) the additive effect is automatically turned off.

this was also fixed in the first PR: https://github.com/Catrobat/Catroid/pull/4216

Second Step: Provide Control of this additive effect to the user

Controlling the additive effect at the start when there is no background was solved, but now we must make sure we give users the ability to control this effect as and when they wish. To do this we created an additional Additivity brick which had 2 values enable additivity and disable additivity, as shown below:

This was added in the second PR: https://github.com/Catrobat/Catroid/pull/4257

Third Step: Introduce the Set Particle Brick

Set Particle Color Brick

The Second brick aims at giving more control to the user, till now the user could only initiate and stop particle effects. This brick lets the user control the particle color, not only will the particles have a different color at the start, but they could also be changed at any given time, giving a gradual fade effect! To create the set color brick we will follow the same steps we followed for FadeParticleEffectBrick.

This was introduced in the next PR: https://github.com/Catrobat/Catroid/pull/4295

Unit Tests and Catrobat Language tests are also be added to ensure the current or future PRs won’t break the flow.

The PR for the discussed changes is: https://github.com/Catrobat/Catroid/pull/4295

Fixing some issues and wrapping Up

Although all unit tests work as expected some Catrobat language tests that were added in the first step used to break every now and then because it was not possible to predict the particle color at any given location at any given point of time. this is being solved in this PR: https://github.com/Catrobat/Catroid/pull/4307

Future Scope

as GSoC was almost nearing its final stage, I have some things that I plan to implement in the coming few days! It includes introducing cool effects using the recently added particle system. Some of the effects include adding realistic Fire, smoke effect, smog effect, and even a custom glow effect! Although these are some cool new features that I would like to add in the future, the foundation stone for each of these features have already been laid during my GSoC period and I hope that the users and enthusiasts love these new features as much as I and the other members of Catrobat loved it! I had an amazing experience during my Summer of Code Program! and would highly recommend others to spend their summers (as well as their free time) doing open source work to improve and hone their development, programming, and organizational skills! Working for free without any kind of conditions in big and diverse projects that are used by millions of people is the perfect challenge that a developer could ask for!

Special thanks to my mentors Wolfgang Slany and Robert Leiner. It was absolutely awesome to work with them and hopefully will continue to work with them if time permits!

Also special thanks to Google for introducing this program:)

Connect with me on Linkedin. Visit https://devsebastian.me :)

Appendix:

1. All my contributions at Catroid: https://github.com/catrobat/catroid/pulls?q=author:devsebastian
2. FadeParticleEffect Brick: https://github.com/Catrobat/Catroid/pull/4216
3. Additivity Brick: https://github.com/Catrobat/Catroid/pull/4257
4. SetParticleColor Brick: https://github.com/Catrobat/Catroid/pull/4295
5. fix to some breaking particle Effect Catrobat Language Tests: https://github.com/Catrobat/Catroid/pull/4307