=========
Resources
=========

MonoGame Getting Started
========================

The following are links to official MonoGame documentation explaining how to get
set up and basic API usage.

- `MonoGame Documentation <https://docs.monogame.net/>`_
- `MonoGame Getting Started <https://docs.monogame.net/articles/getting_started/index.html>`_
- `MonoGame API Reference <https://docs.monogame.net/api/Microsoft.Xna.Framework.html>`_

  - `Game Class <https://docs.monogame.net/api/Microsoft.Xna.Framework.Game.html>`_
  - `SpriteBatch Class <https://docs.monogame.net/api/Microsoft.Xna.Framework.Graphics.SpriteBatch.html>`_


MonoGame Tutorials
==================

Legacy Tutorials - these use terms and have screenshots from an older version of
MonoGame, but include an example of more reusable code for sprite drawing that
we'll look at in class.

- http://rbwhitaker.wikidot.com/monogame-introduction-to-2d-graphics
- http://rbwhitaker.wikidot.com/monogame-project-template
- http://rbwhitaker.wikidot.com/monogame-managing-content
- http://rbwhitaker.wikidot.com/monogame-spritebatch-basics
- http://rbwhitaker.wikidot.com/monogame-texture-atlases-1
- http://rbwhitaker.wikidot.com/monogame-drawing-text-with-spritefonts


Class Resources
===============

:download:`Peer Review Template </_static/peer-review-template.txt>`

:download:`BaseGame For Simple Draw Scaling </_static/BaseGame.cs>`


CSE 3902 Resources Created by Matt Boggus
=========================================

These are archived copies of CSE 3902 class material maintained by Matt Boggus.

:download:`2D Game Information/Art/Sounds </_static/boggus/gameresources.html>`

:download:`MonoGame Information </_static/boggus/gameframework.html>`

:download:`Agile Software Development </_static/boggus/alm.html>`

:download:`Code Quality </_static/boggus/codequality.html>`

:download:`Design Pattern </_static/boggus/designpatterns.html>`

:download:`Visual Studio </_static/boggus/visualstudio.html>`

:download:`C#, .NET, and Software Design </_static/boggus/csharp.html>`


MonoGame on Apple Silicon Macs
==============================

Using MonoGame on an Apple Mac using an Apple processor requires a few
additional steps to follow during setup and while developing your project.
Fortunately, it is fairly straight-forward. Please make sure you follow
*all* of the following instructions to ensure a smooth experience.


How do you know if your Apple Mac uses an Apple processor?
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

There are a couple of ways. First, you can check the "About This Mac" dialog by
going to Apple logo on the top-left corner of the screen, then selecting "About
This Mac". Under "Chip", if the value starts with "Apple" then your Mac is
using an Apple processor. If it starts with "Intel" then your Mac is using an
Intel processor. See below for an example:

.. image:: /_static/mac-m1-chip.png
   :width: 50%

You can also look at the architecture of the running OS kernel with ``uname``:

.. code-block:: bash

   > uname -m
   arm64

If the value written to stdout is ``arm64``, then you're Mac is using an Apple
processor and you should continue reading.


What is the issue?
""""""""""""""""""

The root issue is that MonoGame does not ship with ``arm64`` versions of the
native binaries used for *building* game content (e.g. the MGCB tool). It does
support *running* games natively on ``arm64``, just not *building* their
content. The incompatibility is most often seen as content build errors when
building your MonoGame project, such as:

.. code-block::

   .../Content/fonts/basic.spritefont : error : Processor 'FontDescriptionProcessor' had unexpected failure! [.../MonoGameTest1.csproj]
     System.DllNotFoundException: Unable to load shared library 'freetype6' or one of its dependencies. In order to help diagnose loading problems, consider setting the DYLD_PRINT_LIBRARIES environment variable: dlopen(libfreetype6, 0x0001): tried: 'libfreetype6' (no such file), '/System/Volumes/Preboot/Cryptexes/OSlibfreetype6' (no such file), '/usr/lib/libfreetype6' (no such file, not in dyld cache), 'libfreetype6' (no such file), '/usr/local/lib/libfreetype6' (no such file), '/usr/lib/libfreetype6' (no such file, not in dyld cache)
        at SharpFont.FT.FT_Init_FreeType(IntPtr& alibrary)
        at SharpFont.Library..ctor()
        at Microsoft.Xna.Framework.Content.Pipeline.Graphics.SharpFontImporter.Import(FontDescription options, String fontName) in /home/runner/work/MonoGame/MonoGame/MonoGame.Framework.Content.Pipeline/Graphics/Font/SharpFontImporter.cs:line 29
        at Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor.ImportFont(FontDescription options, Single& lineSpacing, Int32& yOffsetMin, ContentProcessorContext context, String fontName) in /home/runner/work/MonoGame/MonoGame/MonoGame.Framework.Content.Pipeline/Processors/FontDescriptionProcessor.cs:line 194
        at Microsoft.Xna.Framework.Content.Pipeline.Processors.FontDescriptionProcessor.Process(FontDescription input, ContentProcessorContext context) in /home/runner/work/MonoGame/MonoGame/MonoGame.Framework.Content.Pipeline/Processors/FontDescriptionProcessor.cs:line 80
        at Microsoft.Xna.Framework.Content.Pipeline.ContentProcessor`2.Microsoft.Xna.Framework.Content.Pipeline.IContentProcessor.Process(Object input, ContentProcessorContext context) in /home/runner/work/MonoGame/MonoGame/MonoGame.Framework.Content.Pipeline/ContentProcessor.cs:line 60
        at MonoGame.Framework.Content.Pipeline.Builder.PipelineManager.ProcessContent(PipelineBuildEvent pipelineEvent) in /home/runner/work/MonoGame/MonoGame/MonoGame.Framework.Content.Pipeline/Builder/PipelineManager.cs:line 717

You may also have issues running the MGCB Editor application, where the
application will seemingly start but quickly terminate.


What do I need to do?
"""""""""""""""""""""

The following steps should be followed to install the required additional
software necessary for successfully using MonoGame on Apple Silicon Macs.

Install .NET SDK
''''''''''''''''

Start by downloading and installing **both** the Arm64 and x64 versions of the
.NET SDK from https://dotnet.microsoft.com/en-us/download/dotnet/8.0. Make sure
you run the downloaded packages for **both** architectures. To verify you have
installed the required packages, open Terminal and run the following command:

.. code-block:: bash

   $ dotnet --info

This command will dump information about the installed .NET runtimes and SDKs.
First, make sure the following is printed towards the beginning of the output.
In particular, you are looking for the ``RID: osx-arm64`` part.

.. code-block:: text

   Runtime Environment:
   OS Name:     Mac OS X
   OS Version:  14.6
   OS Platform: Darwin
   RID:         osx-arm64
   Base Path:   /usr/local/share/dotnet/sdk/8.0.401/

Then, ensure the following is also printed towards the end of the output.

.. code-block:: text

   Other architectures found:
     x64   [/usr/local/share/dotnet/x64]
       registered at [/etc/dotnet/install_location_x64]

If you see both of these, the required .NET SDKs are properly installed and you
can move on to the next step. Otherwise, reach out over email or during office
hours to debug the issue.


Install MonoGame Templates
''''''''''''''''''''''''''

Open Terminal and run the following command:

.. code-block:: bash

   $ dotnet new install MonoGame.Templates.CSharp::3.8.2.1105


Create a New MonoGame Project
'''''''''''''''''''''''''''''

Open Terminal, ``cd`` to the directory where you want to store your project, and
run the following command. Replace ``ProjectName`` with your desired project
name.

.. code-block:: bash

   $ dotnet new mgdesktopgl -o ProjectName

As an example, if you want to create a new MonoGame project called "MyGame" on
your desktop, you can run the following commands.

.. code-block:: bash

   $ cd ~/Desktop
   $ dotnet new mgdesktopgl -o MyGame

Once your MonoGame project has been created, you will need to follow some
additional one-time setup steps.

.. code-block:: bash

   $ cd MyGame
   $ dotnet tool restore
   $ ln -s /usr/local/share/dotnet/x64/shared "$HOME/.nuget/packages/dotnet-mgcb-editor-mac/3.8.2.1105/tools/net8.0/any/MGCB Editor.app/Contents/MacOS/shared"

At this point, you should be able to successfully start the MGCB Editor
application.

.. code-block:: bash

   $ dotnet mgcb-editor

Note that using MGCB Editor to *build* your content will fail. Instead, copy the
following text to a text file called `build-content.sh` in your project's
directory, changing ``MyGame.csproj`` to match the name of your project.

.. code-block:: bash

   #!/bin/sh

   export PATH=/usr/local/share/dotnet/x64:$PATH
   dotnet build MyGame.csproj

Now go back to Terminal, ``cd`` to your project directory, and run the
following.

.. code-block:: bash

   $ cd ~/Desktop/MyGame
   $ chmod +x build-content.sh
   $ ./build-content.sh

This should successfully build your MGCB content. The ``chmod`` command is a
one-time setup step, but **running build-content.sh is required every time you
add or modify content in your project**.


Teamwork with non-Mac Users
'''''''''''''''''''''''''''

When working as a team with non-Mac users, the above steps can still be followed
except for cloning your project's git repository instead of creating a new
project. You can add the `build-content.sh` file to your project's git
repository without affecting non-Mac users.