2D lighting with soft shadows for MonoGame
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
Documentation Remove code generation for .resx files Jun 26, 2017
Samples Remove trailing whitespace Jun 22, 2017
Source Also default forgotten preprocessor clauses to WINDOWSDX Jul 12, 2018
Tools Fix nuget path in publish script Jun 22, 2017
.gitattributes Init Jun 25, 2015
.gitignore Initial commit Jun 21, 2015
LICENSE.md Create LICENSE.md May 9, 2016
MonoGame.Penumbra.sln Add DesktopGL support Mar 24, 2017
README.md Update README.md Mar 21, 2017


What is this sorcery?

Penumbra allows users to easily add 2D lighting with shadowing effects to their games.

Note that this project is no longer in development. I do try to fix any bugs though!

Platformer2D sample

Getting Started

Building source and samples

The following is required to successfully compile the Penumbra MonoGame solution:

Using Penumbra

Currently available only for MonoGame WindowsDX platform targeting .NET 4.5+!

Install the assembly through NuGet:

Install-Package MonoGame.Penumbra.WindowsDX

In the game constructor, create the Penumbra component and add to components:

PenumbraComponent penumbra;

public Game1()
  // ...
  penumbra = new PenumbraComponent(this);

In the game's Draw method, make sure to call BeginDraw before any other drawing takes place:

protected override void Draw(GameTime gameTime)
  // Rest of the drawing calls to be affected by Penumbra ...

This will swap the render target to a custom texture so that the generated lightmap can be blended atop of it once PenumbraComponent is drawn.

By default, Penumbra operates in the same coordinate space as SpriteBatch. Custom coordinate space can be configured by setting:

penumbra.SpriteBatchTransformEnabled = false;

Custom transform matrix is set through the Transform property.

Working with lights

Penumbra supports three types of lights: PointLight, Spotlight, TexturedLight

PointLight Spotlight TexturedLight

While PointLight and Spotlight are generated on the shader, TexturedLight allows for more customization by requiring a custom texture used for lighting.

Lights provide three types of shadowing schemes: ShadowType.Solid, ShadowType.Occluded, ShadowType.Illuminated

Solid Occluded Illuminated

To add a light:


Working with shadow hulls

Hulls are polygons from which shadows are cast. They are usually created using the same geometry as the scene and can be ordered both clockwise or counter-clockwise. Hull points can be manipulated through the hull.Points property.

For a hull to be valid and included in the shadow mask generation, it must conform to the following rules:

  • Contain at least 3 points
  • Points must form a simple polygon (polygon where no two edges intersect)

Hull validity can be checked through the hull.Valid property.

To add a hull:



  • MonoGame.Penumbra: The core project for the lighting system.


  • HelloPenumbra: Simple sample which sets up bare basics of Penumbra with a single light source and shadow hull.
  • Platformer2D: Penumbra lighting applied to MonoGame Platformer2D samples game.
  • Sandbox: Generic sandbox for testing out various different scenarios.
  • Common: Supporting library providing common functionality for samples.
  • FarseerPhysics: Create physical bodies out of sprites and add them as hulls to Penumbra!