Skip to main content

Context

Easel has a powerful feature called context which, when used right, allows your code to be more succinct and easier to read. When overused howver, it can introduce unintended bugs. Because context has implicit effects in your code that you cannot immediately see, these bugs can be difficult to track down and fix. Good practice around context is needed to avoid these issues.

Choose a limited set​

In your project, you should have a limited set of context variables that you use repeatedly throughout your codebase. This way, you know what to expect, and you can avoid unintended bugs. Outside of this set, you should not use context at all.

Here are some examples of common context variables that could be used in a project:

  • Roles: unit, projectile, scene, dialog, owner, body, ui, camera, space
  • Values: radius, color, luminous, sharp

You can imagine a game where the above variable names are used again and again across many different types of entities, and they always mean the same thing. This is what makes them good candidates for context variables.

As you can see above, context variables tend to come into two sets. Roles are used to describe the role of an entity in your game. Values refers to simple values like color that can be accepted by many different functions in your game. Each of these will be discussed in detail in the next sections.

All roles can be context variables​

When choosing your limited set of context variables, some of the variables should be roles like unit or projectile. Even a complex game should only have a limited set of roles. If you think about it, even a game with hundreds of different types of projectiles (e.g. Fireball, Lightning, Laser, etc.) would still just have one projectile role.

Every role that you use in your project should have a clear and consistent meaning, and that makes them all good candidates for context variables.

See Roles for a deeper discussion on choosing roles for your project.

Which values should be context variables?​

When choosing your limited set of context variables, some of the variables will be simple values like color or radius. This section details what criteria you should consider when deciding whether to include a value variable in your set.

To answer this question, we will look at the luminous parameter as an example. If you are unfamiliar with it, the luminous parameter is used to turn on additive blending for graphics, which makes them look like they are made of light, rather than paint.

Here are some reasons why luminous makes a good candidate for context:

  • Consistent meaning: The luminous parameter is accepted by most graphical functions in Easel, including ImageSprite, Spark and Streak. In all cases, it always turns on additive blending. There are no alternative meanings of the parameter. So if we make luminous a context variable, it is clear what it does because it always does the same thing.

  • One value per entity: If an entity is considered luminous (say for example, a Lightning Bolt), then normally every sprite, spark or streak that forms that entity would be luminous. The entire lightning bolt is made of light, so if you forget to set luminous for one spark, it would look out of place. There are not normally different values for some components of the entity versus others.

  • Commonly used throughout the project: In addition, luminous is a parameter which would be used by many entities in a game. For example, a single spellcasting game might have a Laser, Lightning Bolt, and Fireball, all of which are luminous. It is a parameter that would be used so often that we are unlikely to forget it exists. That means, when we encounter bugs, we are likely to remember that luminous is a context variable, and so we are likely to check it when debugging.

If you follow these criteria, you will end up with a small, manageable set of context variables that are used throughout your project. This will help improve your code's readability and iteration speed, while avoiding unintended bugs.