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 incore
, 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 thecore
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!