Installation and Setup

In this section, we'll be showing you where to get the Ladybug libraries and how to include them in your project files in VSCode.

Prerequisites

To get started, you'll need to install MonoGame and its dependencies. This guide is also assuming you will be using Visual Studio Code as your IDE -- steps will vary with any other IDE.

• .NET Core Runtime and SDK
• Mono Runtime
• MonoGame
• One or more Ladybug Modules, or Ladybug Core
• Visual Studio Code

Setting up the Project

Once you have MonoGame and its dependencies installed and have chosen one or more Ladybug libraries, you're ready to set up your project. A sample project is also available for download here, free for you to use directly or as a reference -- either way, feel free to modify it to suit your needs.

Project Structure

MonoGame projects can be set up in various ways, but we will proceed to show you the way Welcome to Monday sets up their game projects. The resulting project structure is typically as follows:

game_name/
| - core/
| - lib/
| - ref/
| - xplatform/

• The core folder contains the Shared Project which contins the bulk of the game logic. A Shared Project contains code and resource files, but no instruction on how to build these files into an executable. It is used to house all platform-independent code in a central location.
• The lib folder is used to house any extra libraries used by the project. We keep our Ladybug libraries in this folder.
  • It is also possible to keep a single installation of Ladybug somewhere else on your computer and to reference it from there, but we like to include it directly in the game files so that the game will always have access to the exact copy (and version) of Ladybug it was built with.
• The ref folder is used to house asset source files for the game, including audio projects, psd files, and other "editor-friendly" files that can't be directly consumed by the game. We like this approach because we can keep the files together with the game in the same folder, so it makes version control via git much easier.
• The xplatform folder houses a MonoGame project with the cross-platform desktop build target (Desktop using OpenGL). This project has a reference to the Shared Project in core, plus instructions on how to build an executable for the DesktopGL target.
• If other platforms aside from DesktopGL are being targeted, there will be an additional folder for each, e.g. android, uwp, ios, et al. These projects would all reference the core shared project, plus include any code specific to their targeted platforms.

A sample project with this folder format is available for download here, but the following steps will illustrate how to build this yourself.

Creating the Structure

In order to create this project structure yourself, you'll need to install the MonoGame project templates. This can be done with the command dotnet new -i MonoGame.Templates.CSharp. Once you've run this command, you can see all the project templates available to you with dotnet new:

Templates                                         Short Name            Language          Tags                                 
-------------------------------------------------------------------------------------------------------------------------------
Console Application                               console               [C#], F#, VB      Common/Console                       
Class library                                     classlib              [C#], F#, VB      Common/Library                       
MonoGame Android Application                      mgandroid             [C#]              MonoGame                             
MonoGame iPhone/iPad Application                  mgios                 [C#]              MonoGame                             
MonoGame Mac Application                          mgmacos               [C#]              MonoGame                             
MonoGame NetStandard Library                      mgnetstandardlib      [C#]              MonoGame                             
MonoGame Portable Library                         mgpcllib              [C#]              MonoGame                             
MonoGame Shared Project                           mgsharedproj          [C#]              MonoGame                             
MonoGame tvOS Application                         mgtvos                [C#]              MonoGame                             
MonoGame Windows Universal Application            mguwp                 [C#]              MonoGame                             
MonoGame Windows Application                      mgwindows             [C#]              MonoGame                             
MonoGame Pipeline Extension                       mgpipelineext         [C#]              MonoGame                             
MonoGame Cross Platform Desktop Application       mgdesktopgl           [C#]              MonoGame/Game

Now that you have the MonoGame templates, you can create your project folder and then within that folder, create the core Shared Project and one or more "Platform Target" Projects:

mkdir game && cd game
dotnet new mgsharedproj -n core
dotnet new mgdesktopgl -n xplatform

Once you have the Shared Project and your platform target folder(s), you can create the lib folder and put your chosen Ladybug libraries into it. Other folders can of course be created to suit your needs, but this guide will only assume that you have a Shared Project folder, at least one Platform Target Project folder, and a library folder.

Hooking it all Together

At this point you should have a Shared Project (we'll use core to refer to this), one or more Platform Target Projects (we'll use xplatform as our example), and at least one Ladybug library you'd like to use available in your library folder (we'll use Ladybug Core -- ladybug.dll as our example). While all of these are present in your project, they don't have any instructions on how to all work together to create a game.

Exporting the Shared Project Files

First, we'll go into the Shared Project, where we're going to tell it which of its files it'll be providing to the Platform Target Projects that will be using it. To do so, open the core folder (or whatever you may have titled it) and find the .projitems file. This file includes a lot of information on the dependencies of the MonoGame shared project, but what we're interested in is the section towards the middle that reads:

<ItemGroup>
	<Compile Include="$(MSBuildThisFileDirectory)Game1.cs" />
</ItemGroup>

Note: If your .projitems file doesn't have this exact line, don't worry. Find any line starting with <Compile Include= and that'll work just fine. If it doesn't exist at all, feel free to add a <Compile Include=> element surrounded by <ItemGroup> tags at the bottom of the document.

This section of the document lists the files that are being "shared" with Platform Target projects. If you're using Visual Studio, it will automatically generate one line like this for every file in the project. Luckily, that isn't necessary, as wildcards are accepted.

We like to export every C# file in the Shared Project, so we usually replace this line with the following:

<ItemGroup>
	<Compile Include="$(MSBuildThisFileDirectory)**\*.cs" />
</ItemGroup>

Referencing the Shared Project in the Platform Target Project

Now that the Shared Project is sharing its files, we need to show the Platform Target Project where to find the Shared Project. To do this, we need to go into the xplatform folder and find the .csproj file.

Towards the bottom of the file -- after the last closing </ItemGroup> tag but before the final </Project> tag, add <Import Project="..\core\core.projitems" />.

You will have to repeat this step for each Platform Target Project you have.

Referencing Ladybug in the Platform Target Project

While we're working on the .csproj file, we can also add the reference to the Ladybug library. Find the <ItemGroup> section with the <PackageReference> elements referencing MonoGame (if you can't find this, feel free to create a new ItemGroup section by creating a new set of <ItemGroup> </ItemGroup> tags), and add a new line: <Reference Include="..\lib\ladybug.dll">. If you're using multiple Ladybug modules, add one of these lines for each .dll file you have in lib.

You will have to repeat this step for each Platform Target Project you have.

Wrapping Up

With that, you should be all set to get started with Ladybug and MonoGame. In the next section, we'll go over setting up game scenes using Ladybug's Scene Management Module!