Note:

Even my older AI blog posts are starting to feel old already, but I am enjoying the challenge!

New patterns for a new age​

The Bueller quote heading this article has never been more true, it seems almost daily I am reviewing the news, latest posts from ALL of the major partners involved with Agents and LLM's for new patterns, ideas and suggestions. Thankfully, everyone is riffing off each other in a good way, someone suggests or posts something, then someone else builds on that and goes that bit further, whether it is:

• A new LLM logic.
• Improved MCP interfaces and tools.
• Patterns, plans and guidance.
• Token reuse or conservation.

The list goes on, in some ways, it is like the best parts of collaborative science (in some ways, a dark dystopian nightmare), ever creeping forward.

This post was sparked after I followed up on some of these reports and started to see REAL IMPROVEMENT in several key factors in my own research, namely:

• Reduced hallucinations (not gone completely, but significantly reduced).
• Improved memory (yes, you can have memory if you do it right)
• Improved outcomes.

It almost sounds too true, but my workflow has improved, especially with some dedicated research projects I continually use to test new patterns.

Warning: This is NOT a silver bullet, to get more out, you MUST put more in, and thus the cost, depending on what you are using will INCREASE.

My recommendation, as is becoming more of the goal in today’s market, is to HOST your own LLM infrastructure (they have it running on Raspberry Pi's now). It is possible with a little effort, and you can reduce your downstream costs to all but the critical path.

Sadly, this is out of scope for this article, but I will try to add more later.

So, what are these patterns I tease?

Evolving patterns​

The updated patterns I have started employing recently fall into two categories with a single shared theme:

Shared theme - The living document​

The core of the recent updates is to create LIVING DOCUMENTS at the core of any process. This is a SINGULAR document (and you MUST be explicit, as some agents, looking at you Claude, will randomly go off and create masses of documents you did not ask for) which ALL agent calls must update with their state, or you inform it to update at critical junctures.

I have found this works far better than using the Memory MCP, or constantly updating the instructions guide for the agent, and as a separate document, you can create references to it from all other material, including the instructions. In testing, this has been far more efficient and rigorously followed than instructions or memory alone.

• You start the session with the instructions pointing to the living document
• The agent reads the current state with suggested next steps
• It validates any failures or bad paths from previous attempts
• It then plans ahead!

Your mileage may vary, but this singular change VASTLY improves my outcomes. Granted, at the cost of the additional tokens needed to read the document, hence the additional cost. You "can" summarise the document in Agent format if you wish, but I have found this actually degrades its performance and use.

Patterns​

Now to the other meat on the bone, the revised patterns that consume the living document. I have long stated that LLM's are more tuned to the small tasks, a quick fix, diagnosis, but where you need to dig deeper, you have to keep a better handle on the outcome, thus these are the methods I have now turned to using:

It all starts with a defined and reviewed plan​

By far my biggest improvement through LLM use is to focus and narrow its path, to think and to constantly challenge its assumptions. It is NOT foolproof, but it greatly improves your chances of a positive outcome. The whole approach (which is token-heavy) is an almost constant state of review, approval, implementation and review, which when implemented, looks something like this:

• First Agent session - Create the PRD (Product Definition) from a detailed set of requirements, this ensures a list of preferences and outcomes.

• Build an instruction document using the PRD as a reference. Guiding the steps for planning, with KEY steps to avoid creating documents unless requested (stops the multi-document scenario). This might sound counterintuitive, however, they serve very distinct purposes. One directs how to think, the other tells the LLM what to think about.

  Important: Ensure to leave off with a note about the aforementioned Living Document, instruct the agent to check the Living document at the start of a prompt and update it with its intent and finish the query with a statement in the living document as to the outcome. This trains and helps the Agent learn, as well as something to pick up on if you start a completely fresh session.

• Next, start a completely new session (even with another agent if you wish), define the session as a reviewer / architect actor and have it review and improve the plan. Take note of what has changed and follow its thinking. Make corrections where YOU disagree. It is essential you are part of this review process, as key decisions that were maybe not clear in the design become apparent (as often happens in life, poor design leads to poor outcomes).

  Note: You can repeat the previous step a few times with different defined actors, different personas, just as you would in real life. The best plans involve a team, and in this case, it is a team of agents AND YOU!

• At the end, ensure to begin the plan with a Living document record as it delivers the implementation.

Once you are happy with the plan, the next step begins, the following two patterns can be taken:

Plan big but follow your own path​

With the plan in hand, instruct the Agent to document and detail the plan for implementation, ALWAYS ensure you finish with "If you have questions, ask them before beginning" (If you do not, it will not, and it ABSOLUTELY SHOULD). The outcome choice is up to you:

• A singular implementation document.
• Several documents, one for each stage or component, ordered for implementation.
• A mix, depending on your style, backend first, then frontend and UX.

Ultimately, this is a plan YOU will follow, this is my preferred mode as it gives more opportunity to question as you implement or even change your choices. All the agent has effectively done is ratify the architectural state based on your inputs, it is arguably the most human way to use the tools to achieve your goals.

If anything is unclear, ask the LLM to clarify, make changes or explain something "BUT ONLY TO THE PLAN", the Agent should NOT touch the code, that is your domain.

Note: In my experience, when instructing the planning phase, I also interject to ask the Agent to explain each section or block of code, as to its intention, what it is meant to achieve, or what it is supposed to do. This helps guide the implementation as to whether it is the best thing to do. And if you disagree, get it to update its plan, or make your own implementation and then get the Agent to update the spec, then review for ancillary impacts.

This approach feels more like the Agent working cooperatively than running the show and seeing what it comes out with.

Important: At each stage, with each change, ensure to instruct the Agent to update the living document. It might be recorded in the Instructions, but I feel safer double-checking at critical points.

At all points, question everything, it is simply good for the soul and makes the challenge more fun. All that is left is to continue to the end, test everything and the result I have found to be vastly improved.

Tip: Another fun step, but at the cost of tokens, is to ask the Agent from time to time to review what you have actually implemented against the plan and give a status report (helps to reduce human error), marking the document with AI's favourite thing, Icons and Emoji's. As well as providing a summary, as well as giving you a visible checkpoint of your progress.

Automated plan, automated deployment​

The automated plan follows a similar track to the manual implementation path, except you ensure to break out the plan into repeatable and testable sections. It is not as efficient as the manual path, but for shorter and more throwaway experiments, it can be beneficial.

Note: In some cases, I am actually running the two approaches in Parallel! Using the fast route to test theories in advance before incorporating them into plans, similar to prototyping.

Rather than the human doing the implementation, the agent is running the show, but CRITICALLY, not all at once. To avoid hallucinations and dreams of code, each section must be complete, testable and ultimately HUMAN VERIFIABLE.

An example of this was a total conversion of an old game sample in C++ using some REALLY legacy assets. The plan broke down as follows (granted after so many failed attempts in the past):

• Review the project and break up / document the systems and content of the sample.
• Research old asset formats and create detailed documentation of their makeup (critical for migration).
• Build out sample sets of each content type and define a migration strategy.
• For each asset type, build individual pipelines, with human verification at each step.
• Then implement the migration in individual sessions or phases, each phase does NOT complete until the human in the process signs off on it.
• Then plan the implementation, in a stackable way, each implementation building on the last, again with human signoff.

Doing this phased approach with signoff greatly avoids mass delusion and lots of wasted tokens on something that can never ultimately work.

Important: The human as part of the process is essential, not just for the quality of the output, but also as an efficiency surrounding costs and tokens. Yes, it is more effort than vibe-coding a website or app, but the results are FAR superior.

Conclusion​

Thus ends this page in our journey, but the destination is still far from sight.

Learning should never end and we should always strive for improvement, and in my humble view, this is in Cooperation with an agent and not just handing over the keys on a prompt, no matter how detailed, as it is ultimately flawed. We learn more along the journey, take those understandings and evolve a better plan. It is strange, in the many years as a Project Manager, designer, QA and even analyst, this is ultimately how we humans work better, we plan, we question, we revise and ultimately deliver a better outcome. It might not be perfect, but from that, we continue to build better.

Enough musing, back to the code, which is where I feel most at home, with my new pal sitting on my shoulder. (Still not sure whether it is a little angel or devil, but let us see where this leads)

The DarkGenesis blog is undergoing a complete modern redesign. All existing URLs will be preserved for SEO continuity.

Note:

This is a living redesign log; content and layout may change as features land.

2026 needed a refresh​

One of the things I dread is revisiting the design, style, or even template I use for my blog. I spend far too long browsing lots of cool things, find something I like only to find it is either not deployable or has "hidden" issues. The end result is always a trade off between what I want/like and what the template is capable of.

So this time things are different, using tools available (I still refuse to use a site generator), I began the journey using all the tools at my disposal to generate the site fresh, give it a modern look and then use AI tools to help refine/change what I did not like.

Still very much a work-in-progress, but delivered far faster using the tools available to me. I hope you like it.

The rest of this post is my ongoing test to ensure styles work, features are as expected and nothing "breaks" :D

Feel free to skip the rest and move on :P

Example post image​

This post uses a date-based image folder so it’s obvious which images belong to which post:

/assets/img/posts/20251215/redesign-in-progress/

The banner image is referenced via front matter (img:) and can also be embedded inline:

What's Coming​

• Modern responsive design
• Dark mode support
• Enhanced search
• Better accessibility
• Social media integration

Stay tuned!

Markdown support (quick validation)​

Inline code looks like bundle exec jekyll serve.

Strikethrough works: old plan new plan.

Fenced code block​

puts "Hello from Ruby"

Task list​

• Jekyll build works on Windows
• Add more posts

Table​

TL; DR -> Whether or not you are for or against AI, if you do not at least read up on the landscape and the capabilities out there you WILL fall behind. These tools can be used in many different ways and provide support where you least expect it.

It is not about taking away the fun tasks, if you do not want it to code for you, then stop, want to create your own artwork, fine do that. But do not discount the capabilities of the tools because of preconceptions.

You do not need to use it, but understanding what you CAN use it for better arms you in the road ahead to know what you are up against.

Work smarter, not harder​

The evolution of AI tools is ever increasing, as is any technology or area that is adopting these tools. It was already an almost impossible task to "keep up" with advances, causing developers and engineers to keep narrowing their specialties, reducing the mental load to be able to take in the latest and greatest.

Since the unveiling of the current generation of AI tooling, the curve keeps getting sharper and sharper with facilities such as:

• Guides on instructions to provide consistent context between queries.
• MCP servers and their capabilities have increased.
• More and more LLM model services for injecting capabilities into a workflow or service.
• Prompt generation research.
• New agent modes from Chat -> Agent -> Planning -> ...

The list goes on and keeps getting bigger, refinements, new tools, new features. Like any technological "revolution" its speed is increasing.

Note: However one thing remains clear and should not be underestimated, is that AI STILL does not know it is right. So always be on your guard and check the facts! But that does not mean you should not use the tools, just learn the correct ways to work with the tools.

Based on my understanding (at the time of writing), this article aims to impart how my workflow has evolved to a level where I can institute "some" level of trust in my processes with the results from AI.

Note: Fun fact, even today when I started writing this post, I listened to a podcast with Jesse Liberty that featured "James Montemagno on Vibe Coding" ( a term I do not like tbh). In this episode James mentions a few "tricks" I had not considered before, such as using AI to generate the tool or a prompt based on your current activity to enable you to do that activity faster next time. Effectively engineering your workflow as you DO IT.

It starts with a prompt - The Misconception​

I have said it previously, but it is worth repeating. Long gone are the days when you put in a simple question to get an answer or complete a task to fulfil. Sure, on your phone or via your browser, the results are FAR BETTER than dropping it into Bing/Google, but for any serious workflow. Without content/structure and even architecture, the most basic of queries will not result in anything that resembles what you desire. (except for that one day in march where the hares are flocking).

Important: AI is suggestive, it is not indicative. It NEVER knows if it is right, only that the probabilities align with a result compared to your query.

So let us breakdown the critical paths as I understand them at the moment.

Generate Instructions/Agent document​

Instructions or Agent guides are critical to modern AI interactions, they define the background to your request/conversation, define the scope of the work and critically also inform the AI of any boundaries it should not cross. Traditionally, it is also used to define the architecture to follow and conventions to use, but it can also be used as a thought board.

Do not think of your instructions as a static document, it is a living/breathing entity that should grow and learn as your project evolves. Include tips/tricks, any repeated lessons or "daft things" the AI performs that you would rather it did not.

Important: The instruction guide is sent as a pre-context to EVERY chat/conversation, this is information it should know whenever it is sent off to think about anything!

But do not worry about its length or performance, the local agents "tune" the instructions and summarize it for easy digestion. You would be surprised about how much "pre-processing" happens in your client before it even contacts the cloud AI agent.

Simple steps to follow as your project evolves, whether it is a coding session, a Q&A query or just taking notes for a subject:

• If you have an existing project, use the built in VSCode (or other tool) "Generate Instructions" to set an initial framework.
• If you are beginning thoughts for a project, start a conversation with the aim of generating this instruction guide.
• Keep refining the instructions, with or without AI help to frame future conversations.

Above ALL, keep reviewing the instructions manually after generation, do NOT just trust the result, it is meant as a starting point not a finish line. Keep reviewing, updating and even deleting content until you are satisfied with the result. And as your project grows, so should your instruction guide.

Use MCPs relevant to your process​

MCP servers are fast becoming the "go to" tool to assist in local AI support and cut down on the amount of traffic used by cloud agents, they help form, and in some cases, generate results to assist the AI in its journey, these can range from:

Tip: Model Context Protocol servers, or MCP for short actually details the method used to communicate from an AI LLM with a local AI or context agent, a tool used to support AI on its journey. Their capabilities can range from just an API for serving data or results, to full blown AI agents themselves. The MCP protocol effectively allows AI's to talk to each other and work together to reach a goal.

• Simple functions used in calculations or a fact table.
• Headers for local AI agents or models, such as image generation.
• Self-contained LLM's, primarily used for documentation or API references. Useful for keeping the AI bound to accurate source information rather than just the web.
• Proxies to other cloud hosted AI agents, woven together to form a mesh.

Note: Do not be afraid to AI your own MCP server locally, if you find certain areas where you are constantly correcting the AI agent, or need it to use pre-defined terms in its response, then just generate your own server to manage this for you and update your instructions to defer to the MCP server in responses. This can lessen the load in your instructions if you can have an agent maintain it for you.

Each MCP effectively adds another tool the AI can use in the construction of a response as well as off-loading tasks locally to save time or money (credits), or in some cases MANY tools. And there is a growing movement where you can use AI to generate your own local MCP servers, especially for repeated tasks or guardrails.

Important: Too many tools can degrade performance While having lots of MCP servers at the ready is fantastic, be aware you need to limit which Servers/Tools are active at any one time. Giving the AI too many options can severely degrade performance as it need to check the toolset with each interaction (even within a response) to see if there is a tool to help.

Make sure for each interaction/conversation, that you are using the tools that will assist with that thread. Not asking it about code or pull requests, then disable the GitHub MCP tools. Also critical for any language or toolset focused conversations. Just use the tools that will help with your query.

Create custom prompts for repeated tasks​

A recent trick I picked up surprised me how effective it was. If you find yourself either asking the same question, or making the same corrections, or even just doing the same thing repeatedly, then stop and just make a new customized prompt for yourself.

You see these already when in VSCode you hold ctrl + shift + P (or cmd + shift + P on Mac) to bring up the command window, from here you see regular actions available to you based on the extensions you have installed and the MCP servers you have registered. Once activated, they complete a set of tasks using what is available to perform an operation, be it cloning a repository, or formatting your document (my most used command).

But you can also create your own, and again, use AI to help you generate it. In the middle of a conversation when you have completed a task, ask the AI to summarize the task that was completed and ask it to generate a new Command in the tool. You will get the source for the command, allowing you to tweak it to your needs (and likely remove some unnecessary steps) and then save it with a command name, thus, every time you need to perform the same task, save yourself some keystrokes and just launch your command instead.

Leverage resources online​

A common misconception when working with AI Agents, is to assume it is trawling the web for the current/latest information, sadly this is not true (in the most part), LLM's rely on historical information they have been trained on. If there is newer information, it is best to direct the AI to also read specific documents, websites or other sources of information in addition to its trained model.

Important: Although this does not "train" the AI in new information, the data that is gathered is only summarized and used as part of the current conversation. If you asked it again in a new conversation without providing the source, it will not know.

You can add such sources to your instruction guide, although it will only be summarized from the last time you generated the guide, alternatively you can either use an MCP server such as "Context7" (A useful docs MCP) or generate your own MCP server that refreshes its memory from online sources that you critically rely upon, like your companies document server.

Cost Management - The hidden tax​

While many of the tools we use today offer generous free tiers or fixed monthly subscriptions, the move towards "pay-as-you-go" models for advanced agents and API access brings a new consideration: Cost.

Every interaction with an AI is not just the question you ask; it includes the entire conversation history, your instruction guides, and any files you have attached. This "Context Window" is re-sent with every single query. If you have a long-running chat with megabytes of code attached, you are paying for that data transfer every time you press enter.

Important: Token Hygiene To keep costs (and latency) down, practice good token hygiene:

• Start fresh: Do not keep one giant chat going forever. Start a new conversation for each distinct task.
• Limit context: Only attach the files relevant to the specific question.
• Watch the loops: Autonomous agents that "think", "plan", and "verify" can trigger dozens of internal calls for a single user request.

Being mindful of your token usage does not just save money; it often results in faster and more accurate responses because the AI is not distracted by irrelevant noise from 50 messages ago.

Change your workflow​

AI tooling should not be just about work, used correctly, you can use the tools to influence or guide almost any task, such as:

• Guided research.
• Ideation and thought generation.
• Validating preconceptions.
• Applying structure.
• Architecture compliance.
• General validation.

And these are just from my building workflow over recent months/years. Using AI to not just do work, but to plan, evolve, generate more tools to further accelerate your workflow, defining the ultimate development method of DRY - Do not Repeat Yourself.

Tip: Did you know there are several "MODES" of AI usage now? Not just Agentic (Agent) or "ask" (query), but also "Plan", which is great for digging deep and coming up with a stepped plan of actions which you can either get the AI to start working from or do yourself, as well as several others and even custom modes you can create yourself, tailor the experience to meet your needs.

Guided research​

When researching any topic, wading through mounds of documents, websites, information and searching for the latest (or even historical) information can be very time consuming.

Granted, this should be treated as source material and taken with a grain of salt as critical facts will need to be verified. Even with recent advances in correction and validation, it is still just an approximation. In many cases, it is worth asking different agents to read over the results and verify sources for cases.

You might think, why bother, if the information is potentially unreliable what is the point. But the answer is simple, the AI can search through data to find you a shortlist far quicker than any human can, reducing the scope of your research with summaries.

But do not stop there, keep iterating the results upon itself, demand references and lookups to the latest sources to verify the results, which in the end results in data you can rely on for your studies.

Important: Even so, in research and summarizing the research, use your own words. Use the data as refined source material which is just a smaller window of the wider world contained within results. The ultimate aim is to save you TIME, if nothing else, it can also type faster than you can.

Ideation and thought generation​

A concept I have also been using AI tooling for of late is idea generation. You get a half sleep deprived thought or waking moment of "something", it sounds fine in principle but will it work.

This is where, depending on the type of project it is, I will lean on AI tooling to help ratify my thoughts:

• Has this been done before, if so what worked and what did not.
• Is there any market opportunity for such an idea.
• Summarizing options for "go-to market" strategies.

If the idea is a solution, even using GitHub Copilot to form a new project automatically, generating source, identifying workloads and deployment options. Which it will take on, generate a new repository, and start building out the framework of a potential solution (fantastic for web solutions). Give it enough detail, apply references for similar things you have in mind, and set it off. All of which will happen without you being involved (or even at your desk) thanks to workflow agents.

It does not need to end up with something real, except to prove to yourself whether something is valid or even possible. It gives you a framework to build upon and cuts down the time involved in your personal research.

Validating preconceptions​

Often during my development and management life, we build our own internal bias, it is not always intentional and can lead you to incorrect assumptions. My geography knowledge for instance, is waaay out of date.

Most consumers of AI will turn to the agent on their phones for a quick query, usually with FAR better results than a one line google search (with so many Ad results these days), the results are better, but usually very inefficient.

I have been "trying" to teach my family a better etiquette for searching with AI assistance, forming not just a question but also how to form the response, for example:

Instead of just:

What are the best locations to go on holiday in June?

Better to give the AI heads up as to what you are really looking for:

I am looking to go on holiday in June, what are the best locations to visit?  I prefer hot locations (but not too hot) with spa facilities and a good nightlife.  Make sure to also review other visitors reviews of locations and only include places that reviewed well.  Form the results into a table listing the destination, the hotel or cabin, average review rating and links to booking information.  Also check the sustainability rating for the areas to ensure it is not over populated with tourists and has affordable travel insurance (around £30 pp)

This structure of query is simply more informative while staying natural and tries to tick as many boxes as possible for what you are REALLY looking for:

• What is the purpose of the search.
• What are the constraints.
• How you want the results formatted.
• And additional concerns or limitations.

This is just an example, but as time and tide has shown us, the more effort you put into defining your question (and results) the better the output will be and reduce the need for further onward searches to clarify results.

Applying structure​

One of the hardest parts in any software (or other designs) is architecture, how well formed the solution needs to be. What constraints are needed, which conventions should be used and where the checkpoints need to be in order to avoid pitfalls.

Of the many designs I have done in the past, it is always the longest struggle to keep constantly refining the structure around any project, whether it is in design or implementation. What other considerations need to be considered or applied. Even with many years of training and experience, you always wonder "what if" or try to evaluate uncommon scenarios that could affect operation.

Using AI tooling to review the architecture, critically looking for "things you did not consider" is crucial. Even if you choose not to act on the information as it is not relevant, having another set of eyes with a much larger dataset can really help. I have solved many an issue in a junior's design, as have my seniors done for me, so why not also use the tools available for a third set of eyes.

Defining a well architected solution leads into the next section for using AI to ENFORCE that architecture and prevent future works overriding the design (or at least get them to question the approach).

Architecture compliance​

With any well defined architecture, adhering to that architecture can be challenging. But you can use the AI to help provide a ground truth based on the defined architecture, as well as verifying how compliant any development work undertaken is.

Additionally, the architecture itself can be used as a guide for any future work, using the implementation, design or instructions to inform work that is being undertaken.

As an example, I was building a new component within a service driven architecture and the AI tooling correctly identified all the key touchpoints within the architecture to add the new component, as well as adding Unit tests around the feature. It derived everything it needed from:

• The existing implementations
• The documentation associated with the project
• Designed instructions surrounding the architecture and bounds
• And existing Unit tests for other services (in fact it suggested some additional tests which we then implemented across the board)

This also meant that new work complied with the existing architecture and made the final review and update a lot quicker and simpler, I would estimate it reduced the time needed to build the new component by about 80%, meaning I could get more done faster. BUT, I still had to do a fair amount of work to review the implementation, but no more than I would normally.

General validation​

Checks and balances are key for any professional work, in fact I now regularly use either Copilot as a code review agent or use the Copilot review processes for all documentation, not only to check for the usual grammar / consistency, but also to check my own facts, I prefer to always write myself and use the AI as a reviewer and NEVER the other way round (well, except that one time).

There are many tools in the AI world that are available and you will probably find you have already been using a lot of them, such as a spell checker in your documents (a nascent form of AI that is strictly contained), but writing with AI and also double checking your own preconceptions is now far easier. As an author I used about seven different tools in my own personal proofing exercise and with the addition of AI into that workflow, I have been able to reduce it down to three (because it pays not to have all your eggs in one basket) which saves me considerable time in review.

Summary​

Hopefully this article opens some additional thoughts patterns, as mine do almost daily as I use, reuse and learn from my own use. I have gone far beyond the level of "generate this method" or "this error occurs, why?".

Keeping up to date is a struggle, but it does not have to be, include all the tools available to you to make your life easier, or at least smoother. The tools can simply type faster than you, so use that to your advantage.

Important: But even given all the resource, DO NOT trust the result, check it, validate it, challenge the generated pre-conceptions. Even with the extra steps to read through what has been created, the workflow is still significantly faster. So use it when it makes sense, and for those things you take joy in, and keep having fun.

TL; DR -> In short, NO, lol. AI is a tool that can assist you in solving common problems and mixing many different AI tools and features you can help to accelerate your development and the creation of content (at least place holders for your artists to draw from). But, it is also a great source of pain, frustration and injection of complex issues, which you end up using AI to solve only making the complexity worse and harder to understand if you are not familiar with it.

Essentially, the AI CANNOT do it alone and still needs a human at the helm to guide it, correct it and use other tools to generate assets.

It is however fantastic for DOCUMENTING your project and identifying potential issues!

The AI war continues​

As ever progress marches on whether we want it to or not and with the ever increasing power that AI brings, everyone gets split into one of three groups:

• Hey, I can replace people with a prompt and just build project X using fewer resources (completely false, as the total cost of AI far exceeds the cost of humans)
• AI is evil and only scrapes resources from other hard-working developers and should be avoided at all costs.
• AI is a tool; if used properly, it can accelerate your work. However, it can also introduce complexity and challenges if not managed carefully!

Want to see what AI can do for your game development, check the latest result of my adventures :D

Figure 1: MechRampage Final render

In this article I will detail the latest generation in my experiments with using AI in game development, the terrors, the hail Marys, and the pitfalls. As well as some useful guidance for those new to the field.

The project definition​

For this run, I went with a more complicated outline than I have done in the past, mainly due to the experiences I have built up this year, but also to challenge myself and the AI a little more.

Note: Past experiments involved simple block pusher games, 2D shooters, or even snake, just to give the AI a chance.

*Note, no, it failed to even get close most times.

This was the outline brief I went with:

Mech Rampage​

Mech Rampage is a 3D isometric game where the player will navigate a futuristic city, battling enemies and completing missions. The player is a commander managing a team of customizable mechs, each with unique abilities and play styles.

The terrain will be procedurally generated from a set of assets, fielding such arenas as grassy outlands, urban environments, and industrial complexes. Note, all content to be generated initially by the agent and placed in the content folder for loading.

The play area is an isometric projection, allowing for a unique perspective on the 3D environment. The player will be able to navigate the space freely, utilizing the verticality and depth of the environment to their advantage. Control will be through a point and click interface or touch controls:

• When a mech is clicked, it becomes the active unit and the status displays show the stats for that unit
• When a mech is selected, the player can issue commands to move, attack, or use abilities
• When an enemy is clicked, the player can target it for attack or issue special abilities
• When a resource is clicked, the player can collect it or use it to upgrade their mechs

Generating a game from AI​

The world of AI is rapidly changing and it is hard to keep up at times, it has always been this way with technology, however, with AI the sheer acceleration and complementary (sometimes derisive) changes make it harder to fathom your way through this maze.

Note: Full disclosure, while I have a lot of experience in the area of AI tools, I would never class myself as an "expert", I simply know more than some, yet less than others. It is an ongoing learning experience to find the best ingredients to make a good cake. Just keep in mind the rate at which new ingredients are being made is evolving almost as fast as the range of cakes to bake (and not all are good).

The main thing that has changed in recent AI evolution is the level of planning and resources you can throw at a problem to help direct and make the eventual result better, or at least more in line with testable requirements.

Instructions​

Everyone seems to believe that getting the best result out of AI is to create the perfect "Prompt".....

This is simply wrong, at least in this day and age.

Whereas in the past, a simple quick question or request would be enough to accomplish a simple task, it would almost never be what you needed. Even code intellisense, while useful, would more often than not just "get in the way" while you are in the zone.

The resolution to the "quick" answer is effectively to go long, not in the question, but in the context or framework that you provide "up front" to the AI machine in order to essentially give it a frame of reference. This is defined as a precursor document or instruction guide; each tool you use has its own version of this:

• VSCode uses a copilot-instructions.md guide.
• Anthropic uses a claude.md document.

And others have their own variations, but they all surmise to the same thing: a document that describes such things as:

• The aim of the project (the document is meant to be system wide).
• The architectural principles of the project.
• How the AI should go about any task (more on that in the Planning section).
• Any key resources that should always be used.
• What are the strict rules that must be followed (my favorite with Unity projects is to remind the AI that Unity DOES NOT use DotNet CLI commands).
• Instructions on what the output should be, any documents that need to be maintained.

And in the strictness sense of the term, MORE is better, the more you put in, the better your result will be.

Tip: VSCode and its CoPilot implementation even includes a helper tool in its GitHub Chat integration to get you started with Generate Instructions available in the "cog" options in CoPilot Chat as shown below:

Figure 2: CoPilot Chat - Generate Instructions

Some awesome resource for working with these instructions guides can be found at:

• The awesome-copilot repository, chock full of instructions, modes and more.
• The awesome-copilot-instructions repository.
• Essential viewing is the 5 New VS Code AI Features & Settings You Need To Try Today session by James Montemagno.

But let us continue.

Note: For reference, here are the copilot-instructions that I used for the "Mech Rampage" test.

Planning​

A key difference to the way most prompting works, especially if you use AI on your mobile devices or via chats on the web, is using the AI to "Plan" ahead before it even touches code. This will guide it to define a set of tasks and a breakdown of what it is actually going to do. This can take many forms, but as a starter, here is one of my most common patterns:

Planning Approach​

• Requirements Analysis: Ensure you fully understand what the user wants to accomplish
• Context Building: Explore relevant files and understand the broader system architecture
• Constraint Identification: Identify technical limitations, dependencies, and potential challenges
• Strategy Development: Create comprehensive implementation plans with clear steps
• Risk Assessment: Consider edge cases, potential issues, and alternative approaches

These steps effectively FORCE the AI to actually think about what it is going to do ahead of time, giving you time to evaluate and guide its instruction and testing to ensure what you WANT it to build.

Tip: ALWAYS read the planning guide the AI is generating completely, you never know when it might try and sneak something past you that is either not needed or you do not want!

MCP Servers​

In the fight with AI, newer tools and features have come to our aid in the form of Model Context Protocol services (or MCP for short), which are essentially tools and components to help aid the AI in its journey. You might wonder why these all-powerful gods would need a little extra help, and the answer is simple:

Important: ALL AI tools have no memory - Every question you pose is new to the AI each time you ask it.

Sorry, what was your question again?

In case you are unaware, all AI systems are "stateless", meaning each call is new and fresh, the only reason it appears to be continuing a conversation is that the ENTIRE conversation history is sent to the AI "EACH AND EVERY TIME YOU ASK A QUESTION". You may also see a pause in the request at times stating "Summarizing conversation.." where the AI is actually sending the current state of the conversation and getting it to shorten it down to the key points like it does when you ask AI to summarize an email or document. Although NOTE, in this summarization, key things can be lost, statements made, considerations you asked it to make, or even what day of the week it is, the process is not perfect, like any game of "Whispers", the message degrades the further you get away from the question.

Note: A perfect example is that until I used MCP servers, I would regularly have to keep injecting into the conversation "UNITY DOES NOT USE DOTNET", to remind it I had to click on Unity to compile the code from time to time. Thankfully, not a problem with MonoGame :D

To assist the AI, we can implement or provide services ahead of time in the form of MCP servers.

Note: Depending on your usage of AI, the implementation of MCP servers may vary from hosting containers to python/cli runtimes active on your Host. As I am using VSCode, there are built-in options in the editor to get these running for you through the Extension tab.

In my daily routine, the most common MCP servers I use are:

There are many more kinds of server available as demonstrated on the VSCode MCP agents site as well as elsewhere on the web, or you can even Build your own MCP server.

Important: If you host an MCP server, MAKE SURE to also tell the AI in the Instructions that it is available.

Also note, that MCP servers have to be started manually and ahead of time before you start your AI session!, AI is not allowed to start MCP servers for you (even if you tell it to)

Documentation​

If you use AI for nothing else, it is invaluable as a documentation tool. Again, I will stress it is never 100% right (although it is getting closer) so you should always review what it generates, but it will save you HOURS of writing the docs yourself, or, like in my case, actually give you some documentation to start with because you never have time to "circle back" and write something up detailed yourself.

Frequently in my workflow I will take a breather, especially if a feature is close to or is complete, to ask the AI to generate documentation for that feature; it simply becomes second nature. Although, take care, you still have to ensure (usually in your Instructions) to tell it:

• WHERE to place the documentation (else you will find it randomly through your code).
• HOW you want the document structured.
• and (More Importantly) the number of documents you want, ONE BIG all-encompassing guide, or separate documents for each feature. (Otherwise, you will keep returning to the docs to regenerate them.)

Back to the show - Mech Rampage lives​

The generation of this latest MonoGame marvel took some interesting twists and turns, and while not visually appealing, it was, by the end, functional, as shown here:

Figure 3: MechRampage Final render

This was the account of the journey in this round:

• Created the project folder and the new MonoGame game located in the root of the repository.
• Started with the Instruction Guide detailing what the project was about.
• Structured the guide to set out the planning, overall architecture, MCP servers to use and more. Even included steps that an editor (of sorts) should be available in game.
• Started the Sequential Thinking, Context7 and Memory servers to improve the flow.
• Kicked off the "analysis phase" by asking the AI to "Read the Instructions" and then "design the game".
• Once the analysis was good, with a few tweaks, asked the AI to "Generate the game"
• From here on, until I was satisfied it had completed all the tasks, the only thing I had to do (which was different than all other attempts) was ask the AI to "Continue...", repeatedly.
• At the end, I attempted to run the project..... crash... Nothing is ever perfect the first time, not even with AI.
• Then a repeated flow of:
  • Test
  • Copy Error message
  • Paste to AI
  • Get it to apply the result
  • Build
  • Run
  • Repeat

Then at the end when the project was running and no new errors were found, we were done. SHIP IT

Ship it, what could possibly go wrong?

Lessons learned​

In short, we are still not there yet. Things have vastly improved and models do not just spit out an answer, instead they review their answer against the requirements or it compiles before stopping and asking for praise. So much praise both given and requested :S.

Note: About the only thing I really dislike at this moment is the AI's need to placate us, tell us what fantastic ideas we have or for pointing out something is dumb and how awesomely right we are.

I explicitly turn that OFF in the Instructions, it is a sheer waste of tokens and resources generating all that (and it can go on QUITE a bit)

We still have to keep our guard up and check the homework of the AI as it is still 70% of the time (imho) still incorrect, or goes off on a tangent for its own benefit.

In short, I would break the experience down to the following:

• Do not engage in long-running tasks, unless it is for a specific component.
• Spend time with the AI, just doing "Continue" as I did in this experiment is generally a bad idea.
• Look to smaller and distinct tasks to get what you need, either through direct prompting (comments in code) or through chat.
• Mix and match to find what works for your style.
• Do not be afraid to let the AI generate a method/refactor, but then rework the implementation yourself and delete the AI's code. It will not be offended (yet).

Caution: If you do rewrite or replace the AI's generated code between prompts/questions, ALWAYS ask it to read back the code or class again.

Remember, the AI is stateless and uses only its own history for the next prompt, if you do not get it to check the latest state it will ASSUME it is still how the AI generated it!

Summary​

AI has come a long way, vendors are now providing "thinking" models out of the box, although they still need support from MCP servers aligned to the goals and tools used in the project.

But ultimately, it still needs a human at the helm to guide it, tell it when it is going off the rails and to provide assets needed for any game project. If you are going fully AI, they you can still use AI generated content using other tools, or like most other devs prototyping, using free resources as placeholders until you can get what you want crafted.

It may still be possible to structure many more components together to achieve the complete goal (like Unity is experimenting with using its own AI platform, but still says "You should not make money with this, just pay them to play), but that was far beyond my normal exercise for using "out of the box" AI components.

Have fun, and live long and prosper. I may return with another AI lesson later!

Note: Fun fact, I tried to get the AI to do a quick spelling/grammar check on this guide, WOAH, was I so wrong to do that :D

TL; DR -> Unity has its ways, and not all are obvious or easy to overcome, one such issue is with 3D model animations. In short, although animations will play automatically, other times they just do not and it is very unclear why. In this solution, we FORCE animations to run, trusting not our fate to the Unity gods whims.

Full disclosure, for once, this post was written supported by AI (Claude Sonnet 4 in this case), as it was the AI's intensified work that ended up finding the final solution, so it deserves some credit too. Although as a rule, I generally only write myself, with the occasional help of a spell/grammar checker :D

The Problem: Inconsistent Animation Playback​

In the Unity AR application I am building with work, I encountered a puzzling issue where 3D models with embedded animations behaved differently depending on how they were loaded:

• TapToPlace Models: Animations played correctly when users placed models via touch interactions
• API-Loaded Models: Animations remained static when models were loaded programmatically via API calls

This inconsistency created a confusing user experience where identical GLTF files would animate in one scenario but not in another.

Technical Background​

The project, whilst having its own complexity, is built using SOLID and DRY methodologies, each component or service has a single responsibility for any task, instantiating content, loading from an API or performing actions, the only true differences are in the weaving of these components together, such as the User or API driven approaches above. So the situation with 3D models just "behaving differently" was truly baffling.

GLTF and GLTFast Library​

The application uses Unity's GLTFast library to load GLTF 2.0 files.

The GLTF/GLB (Graphics Language Transmission Format) standard is a modern 3D file format that supports:

• Geometry and materials
• Embedded animations
• Scene hierarchies
• Textures and lighting

The Loading Infrastructure​

The GLTF loading pipeline consists of:

1. BinaryContentHandler: Manages GLTF/glb binary file loading
2. PlacementService: Handles content placement and positioning
3. GLTFast Integration: Uses GltfImport.Load() and InstantiateMainSceneAsync()

Initial Investigation and False Leads​

After extensive debugging, we discovered the issue was not related to:

• ❌ Threading problems (initially suspected)
• ❌ Timing delays
• ❌ Main thread synchronization

All the normal suspects simply proved false, exploring various timing and threading solutions because the symptoms suggested async operation issues. However, these approaches proved unsuccessful because they were solving the wrong problem.

What We (AI and I) Tried (That Did not Work)​

// Attempted timing delays
await Task.Delay(100);

// Tried explicit main thread execution
await UnityMainThreadTaskScheduler.Factory.StartNew(() => {
    // Animation activation code
});

These solutions failed because they addressed symptoms rather than the root cause.

The Root Cause Discovery​

The breakthrough came when we realized that GLTFast creates animation components but does not automatically activate them. The difference between TapToPlace and API loading was not timing or threading—it was the presence of automatic triggers:

• TapToPlace: User interactions naturally triggered animation events through on-screen interactions (a Main UI interaction)
• API Loading: No external triggers existed to start animations

Why This Happens​

When GLTFast instantiates a GLTF model, it correctly creates all necessary animation components:

• Animation components with clips
• PlayableDirector components with timelines
• Animator components with controllers

However, it does not automatically start playing these animations. The animations exist but remain in a paused/inactive state waiting for explicit activation.

The Solution: Automatic Animation Activation​

To solve this, we implementing automatic animation activation immediately after GLTF instantiation in the ContentHandler (A component used to spawn 3D content programmatically):

public async Task<GameObject> DisplayContent(/* parameters */)
{
    // ... existing GLTF loading code ...
    
    var targetGameObject = await gltfImport.InstantiateMainSceneAsync(transform);
    
    // 🎯 KEY ADDITION: Activate all animations after instantiation
    ActivateGLTFAnimations(targetGameObject);
    
    return targetGameObject;
}

private void ActivateGLTFAnimations(GameObject gltfModel)
{
    if (gltfModel == null)
    {
        Debug.LogWarning("Cannot activate animations: GLTF model is null");
        return;
    }

    Debug.Log($"Activating animations for GLTF model: {gltfModel.name}");

    // Handle Legacy Animation components
    var animations = gltfModel.GetComponentsInChildren<Animation>();
    foreach (var anim in animations)
    {
        if (anim.clip != null)
        {
            Debug.Log($"Starting Animation component with clip: {anim.clip.name}");
            anim.Play();
        }
    }

    // Handle PlayableDirector components (Timeline animations)
    var directors = gltfModel.GetComponentsInChildren<PlayableDirector>();
    foreach (var director in directors)
    {
        if (director.playableAsset != null)
        {
            Debug.Log($"Starting PlayableDirector with asset: {director.playableAsset.name}");
            director.Play();
        }
    }

    // Handle Animator components
    var animators = gltfModel.GetComponentsInChildren<Animator>();
    foreach (var animator in animators)
    {
        if (animator.runtimeAnimatorController != null)
        {
            Debug.Log($"Starting Animator with controller: {animator.runtimeAnimatorController.name}");
            animator.enabled = true;
            // Animator typically starts automatically when enabled with a valid controller
        }
    }
}

Why This Solution Works​

In breaking down the solution, it implements a "belts and braces" approach, ensuring no matter what kind of animation system is used by Unity, we just try and start any we find.

Universal Coverage​

1. Legacy Animation Components: Uses .Play() to start animation clips
2. PlayableDirector Components: Activates Timeline-based animations with .Play()
3. Animator Components: Ensures animators are enabled and running

Safe Implementation​

• Only activates animations that have valid assets/clips
• Includes comprehensive null checking
• Provides debug logging for troubleshooting
• Non-destructive (does not break existing functionality)

Zero Breaking Changes​

• Maintains all existing functionality
• Only adds animation activation where none existed
• Compatible with both TapToPlace and API loading scenarios

Technical Insights​

As we delve into what makes the solution work, we simply "do not trust" Unity to do the work for us, as we would normally expect.

GLTF Animation Lifecycle​

Understanding the GLTF animation lifecycle is crucial:

1. Import: GLTFast reads animation data from GLTF file
2. Component Creation: Unity animation components are created
3. Instantiation: Game objects are placed in scene
4. ⚠️ Manual Activation Required: Animations wait for explicit start command

Common Gotcha​

Many developers assume that because GLTF files contain animation data, they will automatically play when instantiated. This is not true in Unity with GLTFast. The animations are imported and ready, but require explicit activation.

This behavior is actually correct from a design perspective—it gives developers control over when animations start rather than having them auto-play unexpectedly.

Implementation Best Practices​

The basic take away is to never assume Unity is going to do a job for you, do it yourself regardless. Even though Unity will help you in some scenarios, it will by happenstance, just forget to in the next scenario.

1. Always Activate Animations Explicitly​

// After any GLTF instantiation
var gameObject = await gltfImport.InstantiateMainSceneAsync(transform);
ActivateGLTFAnimations(gameObject); // Essential step

2. Handle Multiple Animation Types​

Modern GLTF files may use different animation systems:

• Legacy Animation components
• Timeline-based PlayableDirector components
• Animator components with controllers

3. Include Debug Logging​

Animation issues can be subtle. Debug logging helps identify which components exist and whether they're being activated.

4. Test Both Loading Paths​

Always test animations in:

• User-initiated loading (TapToPlace)
• Programmatic loading (API calls)
• Any other loading scenarios in your application

Verification and Testing​

After implementing this solution:

1. ✅ API-loaded models now animate correctly
2. ✅ TapToPlace models continue working as before
3. ✅ Consistent behavior across all loading scenarios
4. ✅ No performance impact or breaking changes

Conclusion​

This issue highlighted the importance of understanding the complete lifecycle of third-party library components. While GLTFast correctly imports and creates animation components, it doesn't automatically activate them—requiring developers to explicitly trigger animation playback.

The solution is simple but essential: always activate GLTF animations immediately after instantiation. This ensures consistent animation behavior regardless of how the model was loaded.

Key Takeaways​

• GLTF animation components are created but not automatically started
• Different loading paths may have different natural triggers
• Explicit activation ensures consistent behavior
• Debug logging is invaluable for animation troubleshooting
• Always test all loading scenarios in your application

This fix resolved our animation inconsistency and provides a reliable foundation for GLTF animation playback in Unity AR applications.

I would like to thank my AI Overlords for their assistance in this matter, and offer them this attribution in the generation of this post 😂

Now the real challenge is to figure out who wrote what, but I am not telling, it may upset my future AI Master.

Laters, and I hope you found this educational.

TL; DR -> I am immensely proud of my achievements evolving the MS HoloToolkit into the cross-platform framework that became the MS Mixed Reality Toolkit, and the journey onwards to crafting framework components for the XRTK and finally the Reality Collective.

It seems almost a lifetime ago before I was invited into the Microsoft HoloToolkit team following a strong suggestion by Stephen Hodgson who was already working closely with Microsoft. I had already been working in the XR space for some time and my experiences and skillz seemed a good fit to take things forward. I did not know at the time just how far forward we would go!

HoloToolkit for Unity​

With the astounding launch of the Microsoft HoloLens, the software toolkit that supported it already supported a vast array of features, tools and even baked in UX components. This created one of the easiest toolkit's to use for building for any XR headset at the time.

Figure 1: HoloLens 1 Toolkit feature set

For supporting HoloLens it was second to none, however, it did have a huge gap when it came to making XR solutions, it ONLY supported HoloLens.

The date was 2018 and this is where my journey with the HoloToolkit really took off.

The Dream of a multi-platform toolkit​

Those who know me have experienced my passion for supporting developers and making their dreams of making big things on as small a budget as possible. Building multiple projects, each for different platforms and effectively having to remake a solution each time for a new platform does not sit well with me, when I have a project, content, interaction paths and a structure, why should you be forced to re-envisage it each time a new piece of hardware comes along, it does not make sense.

For platform vendors it makes perfect sense, they want projects to shine only on their platform, using their tools and design language, which is fine for their business models. However, for developers it is just a nightmare that needs to be managed, but why?

Seeing this, I took it upon myself to build up a new architecture / design for the HoloToolkit that would separate out all the critical deliverables of the toolkit whilst instilling a new focus on cross-platform development. Between Stephen Hodgson and I, we turned this dream/architecture into a reality.

• Break Hardware dependence.
• Refactor input for hardware abstraction.
• Define the underlying service framework-driven approach.
• Repackage existing components for Boundary, Spatial Understanding and UX to work from common interfaces.
• High focus on configurability over scene driven components.

The envisioned architecture in its most basic form was represented as follows:

Figure 2: The MRTK vNext architecture

This renewed architecture delivered a vast array of possibilities and performance improvements over the legacy way of building out scene based MonoBehaviour delivery (an 80% improvement in high-frequency areas such as Input and interaction), delivering measurable benefits such as:

• Abstracted Device layer. Allows quick adoption of new devices without affecting existing projects.
• Only a single Singleton / MonoBehaviour in the core project. Single Manager / presence in a scene for easier management.
• Improved performance with all systems being run from the Mixed Reality Manager. Improved scalable Input System.
• Scalable component based architecture. New features can be easily added to the toolkit.

In short, instead of completely rebuilding a project using another vendor's SDK or Hardware API, the project is written against a common interface and a new platform is simply added to deliver the data needed to run the framework.

What went right​

The framework itself was a huge success and adoption was quick due to pre-built configuration profiles being delivered with the project, what would originally take several hours with the HoloToolkit (or other competitive XR packages) now took minutes, as intended the focus was now driven to building out UX, experience and content over "getting things working".

As new hardware platforms were added, either by Microsoft or the community (due to its componentized nature, new platforms only had to exist in the project and they were immediately picked up), adoption was easy.

Microsoft kept expanding the UI framework with new features to further enhance projects built with the new MRTK, each component being another "drop in" feature already wired up to all the critical events to make them work.

HoloLens 2 slotted right in with the new framework, and any existing projects that were built for HoloLens 1 using the new toolkit automatically inherited HoloLens 2 deployment with no changes. Granted, with any new device there are new features and capabilities, but these were extensions on top of the existing framework, making adoption easier.

What could have gone better​

With time and budgets, there was no scope to provide an upgrade path from the original HoloToolkit to the new MRTK, there had already been a lot of angst over recent changes to the HoloToolkit and refactoring/restructuring of how the legacy toolkit was delivered. It was a short term pain and a lot of guidance was provided on how to "step up" quickly to upgrade projects. But in reality, projects needed to be re-built from the ground up with how the new toolkit functioned. (Sadly an experience to be repeated when the Microsoft team decided to re-engineer the MRTK with Unity's XRI Framework for MRTK3).

Not long after the launch of the HoloLens 2 and its adoption into the MRTK, all external (non-Microsoft) were exited from the project due to some changes in the internal management of the Mixed Reality team, this effectively shut out developers such as myself and Stephen Hodgson (and several others) from further development of the project, after so much time and investment to build the framework for Microsoft, some felt this was a bridge too far. A hard lesson to learn in how to build open projects for large companies. The wider team was still encouraged to participate in events and support the MRTK in the community for adoption, but all Microsoft projects and contracts were held in-house and limited information was shared regarding any issues or frustrations in its use. This sadly limited the future development of the framework.

Newer features became difficult to engineer and implement into the framework and some features that needed an overhaul were only migrated into the MRTK, while this did not cause specific problems, the advantages of the new platform were lost on these features and no time was given to upgrade them.

Onwards, the launch of the XRTK - 2019​

Figure 3: The birth of the XRTK

As the MRTK became more of an internal project, the community, spearheaded by Stephen Hodgson and myself (and later others) brought the heart of the MRTK v2 into the public domain, this was supported by Microsoft for wider community engagement as a way to cooperatively build out new features / platforms and components that were compatible with the base MRTK. Numerous fixes and enhancements were driven into the framework (some ending as PR's into the MRTK while it was still accepting community changes) and newer platforms were added such as:

• OpenVR
• Meta Quest
• Pico
• Magic Leap

Additionally, new build processes to automate the building of XRTK projects were created, used to also build and test the framework to ensure reliability for future changes as well as delivery of the entire solution as OpenUPM packages further increasing access to the project and getting teams setup quicker. MRTK however chose to deliver a separate tool to manage delivery of MRTK packages rather than using open source solutions.

The birth of the Reality Collective and the evolution of the framework - 2022​

While the demand for the original vision of a truly cross-platform and cross-device framework, the original design and architecture was still true, there were many concerns raised by the community and some of the developers of the toolkit that it was becoming overly monolithic, features were too tightly bound and specific parts of the framework that were useful outside of XR were locked behind layers of other functionality, a change was needed and thus the Reality Collective was formed in 2021 by Dino Fejzagić and myself.

Figure 4: The Reality Collective

One of the most fundamental changes we agreed on was the breaking up of all the collected components of the framework to allow for better reuse in any Unity project, starting with the Service Framework which was at the heart of everything the toolkit did.

Service Framework​

Figure 5: Service Design

The service framework at his heart decouples functional services and runtimes from the Unity MonoBehaviour shackles, enabling high-frequency operations and reducing performance impacts by 80%, similar to what Unity is trying to achieve with its new DOTS/ECS framework (which requires drastic changes to the construction of your project).

Functionality is effectively containerised into discrete components and through the service framework, they are immediately accessible throughout the project without any hard dependencies.

Another core tenant of Service Design within the Service Framework is the decoupling of configuration for each service through configuration profiles:

Figure 6: Service Profiles

Profiles are independent configuration files that are attached to service configuration, they are decoupled from any Scene based configuration (so changing configuration does not require scene changes) and can even be swapped out at runtime if needed. This enables you to have services with multiple types of configuration and apply the one that best meets the Scene or Project/platform needs. This is crucial for XR solutions where platforms need specific setups depending on the headset they are running on.

All my production projects use the service framework for anything from:

• Application Settings.
• Application State.
• UX design and flow.
• Integration with third party services.

There is so much more behind the Service Framework, so you can read about it here, or check out Joost van Schaik blog where he talks about so many different Service Framework implementations.

Reality Toolkit​

The Reality Toolkit is where is all began, now stripped down to just the essential parts to be more efficient and maintainable, each feature given its own space in its own right to make building projects even easier:

• The Core - Input system, critical definitions and structures, and future proofed elements to be as fast as possible.
• The Player framework - Defines playable areas, the XR rig definition and a multi-tiered Camera / vision setup, automatically setting up the environment in reaction to the headset / environment it is running on.
• The Interaction System - A vast array of building blocks for almost any kind of XR interaction, from Select, Grab, Throw, Pull, Switch and so much more. All ready to work out of the box.
• The Locomotion system - Enables all forms of reusable features to control locomotion for players in XR titles, including teleportation, screen effects and anchoring.

And so much more, and due to the componentized nature, you only need take in those components you want or need to use.

Interestingly, when the MRTK raised up to V3, they took a similar approach to the Reality Toolkit and separated out the Service Infrastructure for Unity's XRI platform. They then tried to re-create the patterns of the Service Framework into the XR Subsystems, trying to retain the approach used by the XRTK/Reality Collective.

However it became too cumbersome for users to migrate to, some of those projects with existing MRTK V2 services actually included the Service Framework instead as it meant they could reuse what they had already built with little rework.

There is even a fully featured sample app available (still actively being worked on) to feature all the components of the Reality toolkit, following a dungeon explorer style game with each room teaching you some new trick or feature:

Figure 7: Sample Dungeon demo

The toolkit is the fastest way to get your XR project up and running and on to whichever devices you want to deploy on (provided the client plugin has been built to work with the framework)

Summary​

XR is still an evolving space, I have worked on and continue to work on so many different projects from Mobile to headset and beyond and AI's introduction is only accelerating its use and development.

I have bright visions for the future and still continue to contribute to open source projects like the Service Framework and Reality Toolkit as time permits, as well as utilize them in production projects (I have added two new platforms to the Spatial Persistence package already recently for Google Cloud Anchors and AR Foundation Image tracking), so where the framework's use in a project needs expansion, all efforts head back into the online projects as well.

Ever onwards!!

TL;DR -> XR is an interesting space with lots to offer, but it is not for the faint of heart as there are many challenges ahead. Checkout my solutions that are live in the market, not fake demos.

In a showcase of my recent efforts, I thought I would share some of the experiences I have been working on. Each has brought its own challenges, from dealing with engines and software, tackling complex integrations between vendor SDK's and achieving the desired implementation, to the often confusing requirements set down by customers or sales.

These solutions are all native solutions built using Unity 3D to achieve the best performance and meet demanding customer needs. Whilst WebXR does show promise, it is still missing key features in public browsers (those not requiring complex advanced options to be enabled) to make them functional. Although I always keep expanding and experimenting with alternate technologies (such as React Native) to give more options in delivery. But above all, I aim to be realistic in the capabilities of any technology.

To begin, I will highlight some of the entertainment experiences or information booths that are often required to show a person or character that can interact with a user, impart some critical information or just to have fun.

Two such examples below use very different techniques to convey a message.

Showcase 1 - 2D Digital Holograms​

The first showcase is A 2D hologram of a person delivering a speech or conversation piece, utilizing several techniques to record, place and then play back the message.

The solution even goes so far as to be able to enable anyone with a mobile device to record their own video and place themselves in space, which is a crucial defining factor to allow everyone using the solution to create their own content and fun.

I personally created an entire scene using multiple holograms of me fighting myself with a sword to win a fair maidens heart.

When users engage with lifelike characters, it creates that "appear" in space, they form a better connection with the content over using a traditional photo (and infinitely more repeatable than having some pour soul wait at the door for every attendee).

| :---: | | Reality verses the digital Universe, as a 2D human hologram faces off against a 3D character |

On the left is a video recording that has been transcribed into a 2D hologram and on the right is a 3D character model.

Showcase 2 - Digital Interactive Characters​

The second showcases a 3D animated character with several interactive components. While on the surface this may look like a simple designed character, but behind the scenes it is fully configurable, speech is through any downloaded audio file with lipsync used to keep the mouth and poses moving, subtitles can be downloaded or generated. If customers want to update or change the character, this can be done remotely as the entire experience is run through configuration.

Characters can provide a varied range of interactions from:

• A fully interactive experience such as a treasure hunt, a simple AR game or interactive back-and-to conversations.
• Simple snippet speeches about achievements or history.
• Enact poses so that users can get photos taken with characters, although only though the back facing camera as AR selfies are sadly not a thing yet.

Depending on the scope of the project, characters can be embedded within the solution (to simplify download, especially in poor network areas), or like Web style projects, the assets for the character can be downloaded to the device (which also allows updates to characters without a new app release) for playing.

I have always focused on reusability and delivering frameworks to build such interactivity, this creates massive cost savings as newer exhibits are rolled out, as well as the ability for installations to manage their own content and not incur residual charges.

| :---: | | The awesome Ada Lovelace comes in for a chat to the Signals Museum. |

This has been deployed to the Signals Museum for their recent launch, I would highly recommend checking them out if you are in the area or planning to travel to Hunstville, AL.

Summary​

This is just the beginning, over the next month I will share more solutions I have developed this past few years, with a few tips and tricks along the way to solve some of the more complex problems faced in real-world XR delivery.

Stay tuned for more demonstrations.

TL;DR -> Ethar is an XR powerhouse, using the latest technologies from leading partners and delivering award winning solutions, while also investing in XR research to make new experiences possible, quick and easy to deliver.

As an avid content creator and educator, these past few years have been tough since I joined Ethar (the premier XR Experience platform). I've loved being here since I joined the team and worked hard to accelerate their vision of creating the worlds first truly cross platform and cross-vendor spatial aware platform, however due to my focus I've not had as much time as I have had in the past to share what I've been up to and demonstrate to others what they can achieve.

The goals at Ethar are huge and we have made great strides to overcome the many complexities of running an XR spatially aware platform, whilst also delivering beyond exceptional work for our clients and AREA research projects.

Whilst I cannot share everything, this article is just a snippet of those solutions I'm most proud of achieving, in a cost-effective, efficient and most importantly, cross-platform way.

Cross-Platform spatial placement​

A key goal of any XR Spatial browser is the ability to locate and localize XR content in a repeatable fashion, not just a tech demo to show something cool, but ensuring the solution is deployable, re-creatable, and efficient. We achieve this in many ways, some using tech we have built ourselves and others through API integration with other partners.

It is important to note that the world needs to share and integrate with multiple specialized partners to succeed. Just trying to build it all yourself is a waste of precious time and resources.

Where we differ from most, is that through our platform we can integrate with multiple solutions at the same time, dynamically switching or collaborating at runtime to fit the demand and needs of the client or consumer. This includes gathering even content and experiences from other vendors with compatible interfaces to truly deliver on the dream of a shared XR experience platform.

Localization through our platform can be achieved using:​

• Image tracking and identification
• GPS localized discovery
• Visual Positioning
• Manual placement with world understanding
• In some cases, a merging of all of these techniques as demand requires it

Simply put, in the digital universe of content and data, we can reliably place and recall information and experiences almost anywhere and at any time, whilst also preserving the protection and permissions of both the content and the user.

Only what the user wants to see and is allowed to see is presented, a keen distinction, no clutter.

| :---: | | Retail solutions where vendor content is discovered and displayed virtually to meet the vendor's needs. |

| :---: | | Browsing the high street and discovering offers and promotions from vendors. |

Enriched interactive content and exhibits​

Content on its own is not enough in the advancing world, seeing things through an augmented lens is cool, but being able to truly interact with experiences opens up a new world of exploration. There are many ways to introduce interactivity, but here at Ethar that alone is not enough, the experiences need to be adaptable and updatable on demand according to our clients wishes.

That engagement can be done in many ways:

• Fully interactive conversations and demonstrations.
• Games and discovery.
• Connected experiences with the real world.
• Long-term rewards and collectibles.

Exhibits and interactions need to feel alive and offer more to the end user than a static piece of content, exploring the digital world and enriching the joy of patrons to museums and beyond needs to make the visit a memorable one.

Ada Lovelace making an appearance and talking to guests, with several opportunities to talk and interact with.

These installations can be historical characters, physical installations or even an image on the wall that starts a treasure hunt around the site, with the digital world there truly are no barriers.

At Ethar, we do not stand still, even in the AI revolution that is ongoing, although tempered with the experience of many technical advocates, as safety is paramount when delivering experiences to customers, especially where children are involved.

Merging the physical with the digital world​

There are many mechanisms available today to scan and digitize physical objects and people into augmented content, what many do not realize is that these capabilities are now a part of the hardware/software ecosystem of the devices we carry in our pockets every day, each with their own unique traits and rules. All that is required of vendors is to successfully integrate then with their solutions, which is where the challenge truly begins. These standards, API's, and capabilities are constantly evolving, even more so since the integration of AI into modern devices.

At Ethar, as we specialize in cross-platform integration which is highly componentized, so that any development in one vendor does not impact others, however, this does not affect our downstream applications as they all use a common interface. Adding more vendors only extends the Ethar platforms reach without causing massive rework in our infrastructure. This enables Ethar to stay ahead of the game with limited cost impact, further benefiting our clients and keeping costs down.

And we do not limit what kinds of content and capabilities can be achieved with the hardware available, such as the 2D holograms shown below that can be captured, preserved and then used in digital recreations in the augmented world.

| :---: | | A 2D Hologram that has been captured on a device and then placed in the world world. |

Our vision for such creations is not limited to single subjects or capture, but intended to enable content creators to recreate entire scenes through augmented reality using characters and content they have captured.

World Discovery and Recognition​

When learning new procedures and processes, or completing complicated tasks, traditional learning tools cannot compete in a growing augmented and AI-enabled world. Procedures are becoming more complicated, the safety aspects of even the simplest task are becoming more costly to maintain and repeating training on a regular basis is becoming mandatory through regulation. This means that the cost of doing business keeps growing for achieving the same output, costs which eventually turn into higher prices or operating budgets.

VR training has already demonstrated significant cost reductions and higher adherence to process in a virtual environment, however, the costs to produce such solutions continue to grow as the demands of digital artists increase with higher production and maintenance costs of these virtual solutions.

Ethar is at the forefront of developing solutions fully integrated with XR and AI to both simplify and enhance training and processes, ultimately reducing the costs involved and also improving safety in the workplace. We are heavily invested in building solutions that are both extensible and effective in improving outcomes in training, rehearsal, and active engagement while performing processes. Work in essence should be assisted digitally and where needed, also tracked (should the need require validation) to greatly improve safety and reduce ongoing costs.

| :---: | | XR-assisted training, identifies the world as seen by the operative and assisted through AI recognition and support. |

Discovering hidden worlds through Augmented Reality​

| :---: | | An AR portal into another world. |

Portals are a fantastic way to showcase the hidden digital world behind windows, doors or magical gateways, even more so when you can actually walk through a door and visit that world (such as the radio operator room on the Titanic above). Ethar's content delivery system allows us to distribute such portals anywhere with any content and even change the frame to enter or just look at the world beyond.

Technology keeps moving on and the techniques are challenging to implement correctly with little performance impact on the devices we deliver to for our customers.

The Service Framework by the Reality Collective​

One of the partners we integrate with is the Reality Collective who specialize in a cross-platform framework for building XR solutions, they provide both an extensive Service Framework that simplifies the creation of a robust multi-platform solution as well as an advanced cross-platform XR framework (the Reality Toolkit) that accelerates XR development (primarily focused on VR solutions at the moment)

The Reality Toolkit and Service Framework by the Reality Collective.

Ethar is a premier partner in this toolkit and helps to extend its functionality and capabilities as this greatly extends Ethar's capabilities as well, showing that with cooperation, it is far better to work together to build solutions and platforms that benefit all rather than dedicating resources to proprietary and locked down technologies. Ethar benefits from both the investments we make and also the further investments by the Reality Collective's other partners and host development team, essentially Open Source has more advantages to in-house development alone. Together we build better.

Summary​

I have wanted to blog and showcase much of what is shown above (and more) but the world does not stop spinning for long enough for me to put pen to digital paper. Even my talking engagements have significantly reduced (here's hoping I got more time this year).

But ever the tech-train continues and it is important to keep skills sharp and up to date, there is no such thing as "one solution to fit them all", so Ethar has to remain agile and keep enhancing it's "toolbox" to meet the needs of our customers, and I endeavor to be at the front, driving that train to an unknown destination. I don't know what it looks like yet, but I am excited to find out!

TL;DR -> .NET 8 language support is now available for MonoGame and opening up a whole new world of goodness and speed for games.

*Note, the information contained below is for those developers who want access to the cutting edge, as it requires access to the development source. (with the exception of upgrading your game to .NET 8)​

The full release of the .NET 8 MonoGame support will be included with the 3.9 release, coming soon.​

MonoGame may have seemed stagnant or unmoving in the past, mainly because of the rigors of a group of developers working unpaid on the development of an OpenSource framework, meaning the focus had to be on what enabled the developers to make money in their own projects based on MonoGame. But thanks to recent investments by ReLogic and our awesome MonoGame community, the MonoGame Foundation was born and more significant investments could be made.

Granted, the MonoGame Foundation board (the majority of the core developers) are still NOT getting paid, but there is a renewed focus and understanding of what is needed to make MonoGame (and its predecessor XNA) great again. (not to say it has not always been great, of course)

So on to today's news (a few weeks late), that one of the first items brought up at the MonoGame Foundation board meetings has now been completed, the upgrade from .NET 6 to .NET 8 for the public version of MonoGame. You can read the nitty-gritty of the change here in the PR for the update, and this article will help explain the rest.

It may also be interesting to note, that the work was NOT done by a Foundation Board member, but by one of the MonoGame community, none other than Aristurtle. Make sure to give them a virtual clap on the back when you see them on Discord!!

• What will .NET 8 do for MonoGame
• Actually, you can build .NET 8 already
• Accessing the Developer version of the MonoGame packages
• Getting access to the .NET 8 developer version of MonoGame with Visual Studio
• Getting access to the .NET 8 developer version of MonoGame with Visual Studio Code
• Do not forget about the tools!

What will .NET 8 do for MonoGame​

Initially, not much. Apart from inheriting .NET 8's inherent speed upgrades and compilation updates, nothing has really changed. Stuff you get for free for being on the latest version of .NET is just that, free stuff.

Of note, one developer noticed a 1.5x performance boost by simply upgrading to .NET 8, everything ran smooth without any tricks or fixes. Just by changing a number!

Simply stating:

The .NET 8 upgrade of MonoGame was really worth it, it is a good release.

What this does enable however, is for MonoGame to start utilizing some of the additional features enabled with the latest and greatest .NET framework, namely:

• Improved Serialization. with even more control over serialization configuration.
• Stream-based ZipFile methods.
• Even more methods for working with randomness.

While it will take time to fully realize some of these benefits in the core part of the MonoGame library, initially providing advantages in the Content Pipeline and the writing of some really cool Content Pipeline extensions, which are a fantastic way to fully empower your content in any MonoGame project.

But you are now free to fully utilize any and all improvements from the .NET 8 SDK without limitation (other than making sure it works on your intended platform).

One small Caveat to the announcement is that the .NET upgrade is ONLY for the public version of MonoGame. For consoles and other private areas (due to the licensing enforced by partners), the team is working hard in this release to get those updated, but that will come later.

Actually, you can build .NET 8 already​

Now, one misnomer to get over at this point, is that you can TODAY, with the release version of MonoGame, actually build a .NET 8 executable for your game, and in that, use .NET 8 features in your project. But the MonoGame Libraries are still .NET 6 and limited to the .NET 6 instruction set, so any functionality you write can only be enhanced in your code and not the base of the MonoGame Framework.

You still get some of the performance gains in your .NET project for the code you write in your game so it is worth doing!

Accessing the Developer version of the MonoGame packages​

The developer versions of the MonoGame packages are currently published on GitHub using GitHub's own NuGet packaging service, which can be found at https://github.com/orgs/MonoGame/packages

You can download each package from here manually if you wish, but it is better to do it directly in your project, to do this however, you will also need a Personal Access Token for your client to successfully authenticate with GitHub to access the packages.

Although the packages are public, like the official NuGet servers, they are actually held behind GitHub's authentication which needs a user account to access.

To authenticate, you need:

• Your GitHub username (or email).
• A Personal Access Token with at least READ access to GitHub Packages.

To create a Personal Access token, simply:

1. Visit the GitHub website, logged in of course.

2. Click on your Profile Picture in the top-right-hand corner of the screen and select "Settings".

3. In the menu on the left, scroll to the bottom and select < > Developer Settings.

4. Expand the drop-down for Personal access tokens and select Tokens (classic).

5. Click on the Generate new token button, select Generate new token (classic)

   GitHub Packages only support authentication using a personal access token (classic). For more information, see "Managing your personal access tokens."

   

6. As shown above, give the token a recognizable name, select the

   read:packages scope

   (which only allows this token to read packages, nothing else) and finally set the expiration date. (For read tokens like this, I usually set the expiration to "Never expire", although GitHub will warn you if you do)

7. When done, scroll to the bottom of the page and click Generate Token

8. Finally, on the next screen, GitHub will show your new key in a highlighted row in the Token list, now VERY IMPORTANT, copy your key from here and save it somewhere securely as GitHub will NEVER show you this key again. The only way to access the key again is to regenerate it by editing the Key and requesting a new one.

Your key will need to be regenerated if:

1. You forget it, basically get a new one and update wherever you used it, for authentication, GitHub actions or wherever.
2. The key expires and you need a fresh one.

GitHub will NEVER ask you for a key and will not send you an email requesting it, so NEVER share it and NEVER publish it to a GitHub repo (even private ones). Only use secrets online.

Now armed with your key, you can use this as your password for authenticating with GitHub to access packages stored on GitHub for repositories your account can access.

Getting access to the .NET 8 developer version of MonoGame with Visual Studio​

Starting with Visual Studio, as it is the simplest to do, upgrading MonoGame to .NET 8 is as simple as adding access to the GitHub NuGet package source and updating your packages.

1. Open your MonoGame project up in Visual Studio

2. Right-click and select properties on your Project File (not Solution file), then change the Target Framework to .NET 8.0, as shown below:

   

3. Save and close the window, which now changes the building of your project to .NET 8

4. Next, we need to add a new NuGet source so that you can access the developer packages instead of the publicly published ones on NuGet. Right-click the Dependencies branch of your project and select Manage NuGet packages.

5. From here you can see (by default) what NuGet packages are installed in your project, for which you should see the existing MonoGame packages. Now, click the COG icon next to the Package Source drop-down in the top-right-hand corner of the screen, which will bring up the Package Sources configuration for your project.

6. We now need to add a new source to be able to select packages from the MonoGame GitHub repository, click on the "+" button in the top-right-hand corner of the window which will add a new item to the list and select it (if it does not select it, just select the item labelled "Package Source").

7. Next, enter the following details:

   • Name: MonoGame Development
   • Source: https://nuget.pkg.github.com/MONOGAME/index.json

8. Once you have entered the details, click on the "Update" button to save the changes and you should see the updated screen below:

   

9. Now just click OK and select the new Package Source in the drop-down (if it is not selected already)

   The first time you access the MonoGame developer NuGet source on GitHub, you will be asked for your authentication credentials. Simply enter your GitHub Username (or email) and your Personal Access Token (for the password) that you generated earlier to progress.

   

10. Sadly, all we can still see are the existing Release packages at this point, to see the development versions you need to also check the "Includeprerelease" checkbox next to the search bar at the top of the screen, and WHOOSH, the MonoGame packages list will update to show the VERY latest versions.

From here you should simply be able to select the installed packages and update them to the latest without issue. Congrats you are now using the .NET 8 version of the MonoGame Framework!

Next Step, jump to this section to also update the MonoGame tools, e.g. the MGCB content tool.

Getting access to the .NET 8 developer version of MonoGame with Visual Studio Code​

For Visual Studio Code, the flow is a little more manual and also a bit trickier as we no longer have a UI in which to make changes, so we need to apply the updates by hand.

1. Open Visual Studio Code in your MonoGame Project folder.

2. Select the CSPROJ file in the folder tree.

3. Change the TargetFramework value from net6.0 to net8.0. (yay your project will now build for .NET 8)

   <TargetFramework>net8.0</TargetFramework>

4. Next, to be able to access the GitHub Packages, we need to authenticate with GitHub to access the developer packages, open a new Terminal Window in VSCode ("Terminal -> New Terminal" or "Ctrl+Shift+'") and then type the following:

   dotnet nuget add source --username <your GitHub Username/> --password <your GitHub PAT/> --name MonoGame "https://nuget.pkg.github.com/MonoGame/index.json"
   

   Making sure to replace the username and password with your GitHub credentials, your username and the Personal Access Token you generated.

   

5. With the authentication in place, enter the following command for each package you have installed:

   .NET add package MonoGame.Content.Builder.Task --version 3.8.1.534-develop

   To check the correct version to use for the packages you want to install, visit the Packages list on the GitHub repository and click on each package to see all the versions for the package and even the command-line command, as shown above.

If you now check the Solution Explorer tab in the Browser window on the left, you will see the dependency packages updated to the development versions of MonoGame (assuming your nuget.config is configured with the right credentials)

Do not forget about the tools​

You have updated your project to .NET 8 as well as your MonoGame Framework dependencies. So, why when you do a build does it still use the old .NET 6 versions of the MonoGame Tools (like MGCB)?

The simple answer is because you are still telling it to.

To update your project to use the newer .NET 8 version of the tools, you also need to update the .NET-tools.json configuration located in your projects .config folder.

Simply edit the file in Visual Studio or VSCode and swap out the older 3.8.1.303 version number with the newer version you installed with your packages, which at the time of writing was 3.8.1.534-develop, as shown below:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    ".NET-mgcb": {
      "version": "3.8.1.534-develop",
      "commands": [
        "mgcb"
      ]
    },
    ".NET-mgcb-editor": {
      "version": "3.8.1.534-develop",
      "commands": [
        "mgcb-editor"
      ]
    },
    ".NET-mgcb-editor-linux": {
      "version": "3.8.1.534-develop",
      "commands": [
        "mgcb-editor-linux"
      ]
    },
    ".NET-mgcb-editor-windows": {
      "version": "3.8.1.534-develop",
      "commands": [
        "mgcb-editor-windows"
      ]
    },
    ".NET-mgcb-editor-mac": {
      "version": "3.8.1.534-develop",
      "commands": [
        "mgcb-editor-mac"
      ]
    }
  }
}

Done, next time you perform a .NET restore or build your project, the latest version of the tools with be downloaded and made available (they will not be available until you do your FIRST build after making the update)

*Note this is still a manual task. Every time you update the dependencies, you will also need to update the tools versions.

Conclusion​

To the beginner, this upgrade will not mean much at all, except to state that you will be running on the latest "supported" version of Dot Net (as .NET 6 is now in maintenance only), which also means you will get all the latest fixes and updates to the backbone of your project. As well as the modest speed improvements from the latest and greatest of .NET.

For the more adventurous, newer C# features and .NET 8 specific functionality are now within your project, so much so that I couldn't fit them into a single article :D

But you can check out the .NET 8 docs for even more details.​

I wish you well on your continuing adventure with MonoGame and make sure to keep an eye on what the Foundation will promise next (but no Galactic Empire falls predicted yet if you are watching the Foundation TV series).

TL;DR -> With a little effort, publishing MonoGame projects to the Web is possible, so long as you remember it is the Web and you cannot do EVERYTHING!

When it comes to GameJams, like the one mentioned in this post, pushing out the finished project as an EXE or Appx usually results in your project either getting downvoted or ignored, because who wants to infect their machine with an unknown just to test out a Jam project. This applies to most Game Engines out there that are not web-based, including MonoGame, but thankfully due to the hard work of Nikos Kastellanos (NKast) there is an option available to us.

Now you have to keep in mind, that the Web is NOT your desktop or some high-powered beast, sure, there are continual developments to make Web projects work better or support more features, but it is unlikely to match that of your modern desktops or consoles. Some things either do not work because they are too complex, others because there is insufficient support in all web browsers or devices. So long as you keep in mind the limitations (usually only found by trying to run your game in a browser), then you can truly fly.

Personally, Keep your expectations moderate. First, make your project work with the minimum, then just add more until it breaks :D. Start with the keyboard only and go from there.

• Welcome to the KNI project
• Installing the Templates
• Making a build
• What could go wrong
• Extra credit, publish to GitHub Pages

BIG thanks to NKast For the amazing work with the KNI project which offers another extended way to build MonoGame projects with some additional platforms and features!

Welcome to the KNI project​

MonoGame is an awesome game development framework, made even more awesome by the growing community that surrounds it. A prime example of this is the KNI Engine made and supported by one of MonoGame's long time supporters Nikos Kastellanos (NKast), their tireless devotion brings non-other than Web Support plus a host of other features for projects written using MonoGame.

Like MonoGame, KNI supports the Microsoft Public License for the majority of the code, with a few proprietary exceptions which are detailed in its components. KNI is free and open-source, however, maintaining and expanding the framework requires ongoing effort and resources that relies on the support of the community to continue delivering top-notch updates, features, and maintenance.

KNI Supports the same platforms that MonoGame does (because it is a fork of MonoGame) plus a few additions, which include:

• Additional Math support.
• A WPF based MonoGame Content Pipeline editor.
• Video player support.
• An improved Font Processor.

Plus a few performance tweaks for KNI based projects. Worthy of checking out!

Installing the Templates​

Now, unlike base MonoGame these days, KNI does require a full Visual Studio 2022 installation, mainly to support the additional Project templates that KNI provides, these are all installed by the KNI Engine installer (much like MonoGame did before it upgraded to .NET6 in its entirety):

KNI Engine Releases - Latest (at time of writing) v3.9.9001​

Like MonoGame, most of the libraries behind the templates are published on NuGet, but the Project templates (like the Web project template) still require Visual Studio to create them. (Maybe with your support this can be updated in the future!).

• Simply run and install the KniSdkSetup3.9.9001.exe to install the templates.

At the time of writing, there is a Known issue with the Visual Studio templates, which is mainly Visual Studio's fault (honest), whereby the templates may not immediately show up and require either:

• Restarting Visual Studio a "few" times.
• Require running the command devenv /updateConfiguration in the Visual Studio installation folder, e.g. C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE.

If your User Profile is not in the default C:\Users folder, you might also have to check/update your Visual Studio "locations" setup and move/copy the installed templates there:

Just be sure to run the above devenv /updateConfiguration command AFTER moving them to update Visual Studio.

Maybe with your support, this situation can be improved. All it takes is a little support. But once you are working, you can be ready to fly.

Making a build​

With the templates installed and everything ready, you should have access to the new KNI templates, and for this article more importantly, the KNI Web Browser Template as shown below:

Just create your new project using this template and you are already 90% of the way there:

Running the project results in a new Web Browser being launched against your local machine, ready to test and play with:

Fantastic, so what was too hard about that?

KNI Web uses Microsoft Blazor (which uses Razor files) as the backend, which is a C# compiled Web system for building web apps. It is really useful as MonoGame is C# based and Blazor is a C# based web system, it just works. Some other Web solutions for MonoGame used a cross-compiler to turn C# into JavaScript, but Blazor is just cleaner and more efficient.

Looking into the project, you should see a few subtle differences, which we should discuss, so that you don't change anything you should not by mistake, namely:

Out of the box, you should not need to change anything and the only thing you will need to keep in sync is the NAME of your Game class and the entry point in Index.razor.cs, in the same way we do for other MonoGame projects between the Game class and the Program class.

Here is a GIF of the GameState Management sample (with a few alterations) running using a KNI Web Build.

What could go wrong​

Now, this is the web we are targeting and there is a lot of history and patches to make modern web browsers work, so it should come as no surprise that not EVERYTHING is going to work out of the box:

• Some features are missing, like GamePad and Touchscreen support.
• Some shaders may not work as expected, or require reduced features.
• File access can be... Tricky, pesky permissions.

To name but a few, no doubt there are more, much more. But this being an Open Source project, if you have the skills and are willing to contribute to make it better, I encourage you to do so!!.

When you do hit an issue, and more likely than not I am afraid, you will, you will see the following result when you run your project:

A pretty purple screen with a "Reload" option, which is not really that helpful on its own and Visual Studio is no help here really because you have left the confines of your debugger and entered "The Web Zone"!

Luckily, most browsers have an "F12" developer option, so by pressing "F12" you will get the not-so-friendly "Web Debugger" window, as shown below:

These outputs are more friendly to Web Developers (Well, I assume so?) full of lots of information to help you diagnose what is going on, in this case, the issue was simple:

The sample was using a GamePad for input and GamePads are not currently supported using the KNI Engine for the web.

If you are only doing a web project, just fix / remove the offending code, if you have a multi-platform project, then just encase the offending code with the following pre-compiler definition (#if):

#if !BLAZORGL
                CurrentGamePadStates[i] = GamePad.GetState((PlayerIndex)i);
#endif

Which will exclude the offending lines from being included in the Web Build (just make sure things still work / compile).

Feel free to experiment and play, and for those cunning individuals who are experienced in Web Development, I encourage you to help enlighten those who are not.

Extra credit, publish to GitHub Pages​

Having a web build on your machine that you can view locally is all well and good, but what about everyone else? You cannot exactly ask them all to come to dinner to view your creation, what about pushing it to the web?

To get your build out there, you have a couple of options:

• Painstakingly setup a web host, build your project, connect to your host, upload your files and pray everything works. or
• Let GitHub do it for you. Hosted for free, using free time and none (well a little) of yours.

Thanks to GitHub actions (automation) and GitHub Pages (free static web hosting) we can manage the source of our project online and then create/update a build every time we push an update to source control.

To achieve this, assuming you have a GitHub repo setup and have pushed your source code to it, the tasks we need to complete are:

• Configure the permissions for automation.
• Setup GitHub pages.
• Create a GitHub Pages deployment workflow.

As easy as 1,2,3, honest.

Configure automation permissions​

Because we want our automation to publish content to GitHub pages, and write back to the repository, we need to allow it to (by default, it is turned off). To do this, navigate to "Settings -> Actions -> General -> Workflow Permissions" and set the option to "Read and write permissions" as shown below:

This allows the automation to publish on your behalf.

Setup GitHub Pages​

Enabling GitHub pages is very simple and GitHub continually works to improve the flow to make it easier and easier.

Next, you need to:

• Navigate to "Settings -> Pages"
• Change the "Source" to "GitHub Actions"
• In the selection that appears called "Static HTML", click on the "Configure" button.

Done, there is more to do, but GitHub Pages is now setup. Now for the final and slightly trickier part, the automation workflow.

Configure your deployment workflow​

Following on from the previous step, you should now see the following default workflow setup, which is close but will not build our MonoGame project.

To get the result we want, we need to add the following:

• Setup .NET 6 on the automation host.
• Build/Publish our Blazor webpage complete with our MonoGame project.
• Package the build output, not just the entire repository.
• Deploy (this is actually there, but we need to check the order)

The updated YAML should be replaced with the following:

# Simple workflow for deploying static content to GitHub Pages
name: Deploy MonoGame web project to GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:


# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write


# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.

# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we are just deploying
  deploy-to-github-pages:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Setup .NET Core SDK
        uses: actions/setup-dotnet@v3
        with:
          dotnet-version: 6.0.x
      - name: Publish .NET Core Project
        run: dotnet publish Platforms/Web/KNIBrowser.csproj -c Release -o release --nologo
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload wwwroot from publish action
          path: 'release/wwwroot'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

The critical elements to watch out for are:

• "Publish .NET Core Project" - Make sure the csproj file path is correct. In this instance it is "Platforms/Web/KNIBrowser.csproj"
• The "Upload Artifact" path, which selects the files from the build to upload. By default the "dotnet publish" command outputs to the root of the folder.

If in doubt, run the commands locally in your project folder to make sure you get the output you expect.

Click save and "Commit to main" (or create a pull request) to activate the workflow.

WARNING this will run straight away, as the workflow is activated on checking in code. But do not worry, you have 2000 minutes of FREE time on GitHub for automations.

Check the Action output​

Providing everything is correct, you have put in the paths correctly and checked it DID actually build locally, then you should get the following result:

Clicking on the completed Action, you shall see the output of the Action, INCLUDING the URL that your build was actually published to:

Check out my build here:

http://darkgenesis.zenithmoon.com/GameStateManagementSample-Web/​

Danger Will Robinson​

One issue I did hit which actually prevented my build completing, required me to edit my KNI Engine csproj file and remove a line. The line in question was:

  <Import Project="$(MSBuildExtensionsPath)\MonoGame\v3.0\MonoGame.Content.Builder17.targets" />

Rather ironically, local builds will work fine and run with this in, but automated builds will not. Without it, everything is squeaky clean. (fingers crossed)

The game is afoot​

We have come to the end of this little web journey, I hope others are encouraged and excited to ship your games or hack projects to the web to demonstrate your skills, especially if there is a GameJam going on :D.

Here is hoping this is a little light in the darkness to get you going!

TL;DR -> Getting started with MonoGame is easy, mastering it takes time. So, throw all that out the window and get hacking instead!

The 5th annual MonoGameJam is kicking off soon on the 30th November 2023, which is by far one of the best ways to throw yourself into MonoGame and learn something new:

• Your next engine framework of choice.
• Try something new and exciting (granted usually hair-raising).
• Test out some new technique or skill.
• Have fun and throw things at the screen or speakers until something sticks.

Not quite the vaulted heights of the days of DreamBuildPlay in the past, which launched the careers of so many indie devs such as Ska Studios with Dishwasher Samurai, Smudged Cat Games with The Adventures of Shuggy and even Humble Hearts with Dust, An Elysian Tale.

Bold games for a bold time, and who knows who/what could be next!

• What is MonoGame
• Understanding MonoGame game building
• A great sample to start with
• Services, addons and more, oh my
• Dream Big

What is MonoGame​

If you have been hiding under a very big rock, you might not have heard of MonoGame (unlikely, but possible). MonoGame is a game building framework that focuses on handling all the complex requirements for shipping games on multiple platforms, such as Windows, Android, Xbox, PlayStation and so on, letting you get on with just writing code/art/shaders/etc and so on (just, hah, :P)

In short, MonoGame is a C# based Game Framework (not an engine like Unity), where you write code once, then MonoGame compiles your code for multiple platforms enabling to you spread your wings faster.

To know more, check out MonoGame.Net​

Understanding MonoGame game building​

Getting started with MonoGame is very easy, no matter which platform you are building from, be it Windows, Mac or Linux and the best place to get started, unsurprisingly, is the MonoGame Getting started guide:

Getting Started with MonoGame​

The guides walk you through setting up your machine environment, installing the tools and the MonoGame Framework (most important) and then leading you down the basic path of writing your first game, including content.

For more details, check the MonoGameJam5 site for links, or browse the catalogue of community samples and courses available on the MonoGame website.

A great sample to start with​

My personal favorite for any GameJam involving MonoGame is the GameState Management Sample, originally from Microsoft and updated for MonoGame.

The sample provides a simple game screen management system, ready to be used as a starting point for games on Windows, iOS, Android and more, complete with reusable code to manage all the screens (including transitions) you might need for a project. Even including pause and options screens. It really packs a punch.

The sample is comprised of:

Here is what it looks like:

Enough to get you started on your Hack without worrying about all that on screen "menu" stuff.

The GameState Management Sample​

Services, addons and more, oh my​

If you are thinking bigger than a simple paint program or block pushing game, you might want to add things like Physics, Saving and Loading, AI, Effects and more. Thankfully the MonoGame community has your back with a wondrous collection of resources, libraries and tools available:

I might suggest having a glance through the list below BEFORE the hack to pick your favorites, there are a LOT!

• The Awesome MonoGame library of "stuff - Chock full of links to stuff that will keep you going.
• Nuget (pronounced NewGet) - The place to look for dependencies to add to your project (it is also where MonoGame is hosted). Just add a reference to your project and get the latest version quick and easy.
• The MonoGame Community tutorials list as previously mentioned, a one stop shot of promoted materials from MonoGame by the community. (insert your name here if you also have stuff to shout about)

And much much more!

Dream Big​

Like most GameJam's, the theme is yet to be announced but that's not to stop you getting a blank slate ready and getting some quick reading done. In this ever-expanding world of AI nothing stopping you from asking your robot overlords for help (yes, they even help with MonoGame code) in sculpting your dream, above all, have fun, learn well and put your best thumb forward!

TL;DR -> It is as simple as Initialize, LoadContent, Update, Draw, UnloadContent and finish, with a little sauce in between.

Every Game, Program or process runs on a specific loop, it might go through just once, or as is in the case with Games, the loop continues until the game is over, finished, kaput, crashed or simply closed (but who really wants a Game to ever end :D). Put simply, this is known as the Game loop, and whether it is Unity, Unreal or MonoGame, they all have their own specific order of things.

This article will walk through MonoGame's Execution event order and set out what you can and cannot override to make it your own.

Although personally, and with every MonoGame project I've been involved with, I have extended the Game Loop and never been brave enough to actually OVERRIDE it :D.

• The full breakdown
• The simpler view
• Which events can be overridden
• Game Components
• Basic Game Components
• Drawable Game Components
• Check the samples

BIG thanks to Aristurtle for the original image, credits here! Check out his work as it is amazing in the MonoGame space!

The full breakdown​

The Full MonoGame execution order is a bit much to take in, but I put it first so you can see the full range of what is going on behind the scenes while your Game is Running.

In short, the full execution is like this:

There is a lot more going on behind the scenes to make the Game Loop happen on so many different platforms, from Graphics, Input, Audio and more going on, but the above is a simplification to show the full workings.

The following sections will break this down further for reference.

The simpler view​

Breaking down the core loop into a more digestible reference, the actual Game Loop can simply be described as:

LoadContent and UnloadContent can be called at any time, and usually are when you are switching from screen to screen, level to level, trying to keep ONLY those assets you actually need in memory at the same time. If an asset is not being used, you should consider clearing it out to save those precious memory bytes and cycles for the main event.

Update and Draw are called constantly while your game is running as fast as your machine can run them. By default, MonoGame uses a FixedTimeStep based on 60 FPS (Frames Per Second), doing its best to keep the GameLoop running at a constant speed regardless of device, however, this is NOT GUARANTEED, as if your game takes longer than expected in your Update cycle, the Draw cycle will be late, the reverse is true also.

Changing from Fixed Time to Dynamic speeds​

To allow faster speeds, you will need to alter the timing setup for MonoGame by either setting the TargetElapsedTime to an expected framerate, e.g.

    // Target 30 FPS
    this.TargetElapsedTime = TimeSpan.FromSeconds(1d / 30d); 

Or you can disable FixedTimeStep IsFixedTimeStep = false, and manage all the timings yourself, although this too comes with its own specific considerations. There is no spoon.

My recommendation is to just use the defaults until you run into an issue (or know specifically what you are doing), as the defaults will handle most situations all by themselves, in my honest opinion (for what it is worth).

Which events can be overridden​

In some cases (most when you are dealing with MonoGame projects), you need to override the base implementation of MonoGame events to build your project. Some like Initialize, LoadContent, Update and Draw are well known, while others may not. Here is a full list of the events you can adapt to your needs in your game, all of which are described above:

The sample project linked to this article is available to demonstrate these calls in action.

Game Components​

An underrated feature of the original XNA and now MonoGame Framework are components, essentially these are small implementations of Game Code that you simply pass on to the Framework to handle and run, and they just run (so long as they are registered). Game Components come in two flavours, one building on top of the other:

• A Game Component - A basic Game like class that is Initialized and then updated by the Update event in the game. Like a spawning manager that just needs to kick things off as levels progress, or maintain the state of "things". No drawing, just running.
• A Drawable Game Component - An extended version of a Game Component that also received the Content Loading/Unloading events and the all-important Draw event. Good for drawing enemies on the screen, or particles.

Let us delve into these a little more, into how their events are handled.

Basic Game Components​

Games require a lot of features and components in order to run, some are responsible for things you see, and others are not, such as Audio Managers, Networking and more.

This is where Game Components shine, allowing you to simply register a "Component" with the framework and then MonoGame takes care of it running in the background, all you need is a reference to it in case you need to disable or unregister it, or if the will takes you, to make changes to it.

As shown in the MarbleMaze sample (currently still just XNA but easily upgradable), the AudioManager demonstrates a simple-to-use system, where a single component controls all audio for the game. No other game code updates or initializes it as it runs in the background of the game as a Component.

Very useful for such scenarios.

Drawable Game Components​

Drawable Game components extend the base Game Component architecture by also subscribing to the Content and Draw calls from the main Game library automatically, the biggest benefit here is that they are totally automated and draw in the order they were added to the Games "Components" list.

A great example of these is the Particles2DPipeline sample which builds on top of the excellent 2D Particles sample and demonstrates some complex particle systems which are dynamic due to their use of Components, as shown in the Particles 2D Game class where the effects are loaded based on a set configuration, which can be changed.

Ultimately, these are then activated and disabled to change how the effects are demonstrated with minimal changes to the actual game code.

Check the samples​

The XNAGameStudio Archive contains all the previous XNA examples and more, most are still in their XNA format but are easily upgraded to MonoGame by copying out their Game code and assets, a few have already been upgraded to MonoGame already, here.

Although at the time of writing, only the GSM Sample has been updated to MG 3.8.1, it is a work in progress and a lot of effort to maintain.

But in all cases, you can walk the code and see the various patterns that demonstrate the MonoGame events in action.

The sample included with this article demonstrates the events described and shows how often events are fired. It also outputs the events to a CSV file in the Game's run folder (by default /bin/Debug/net6.0).

Summary​

A very theological article to give you more of an understanding of what goes on under the hood of any MonoGame project and some hints if you specifically need to know when a piece of code will be executed and run.

Hopefully, this will aid you on your MonoGame journey.

TL;DR -> Today, cross-platform projects are easy to setup (except UWP), with .NET7, it gets easier. Read the article for the How-to!

Most Game projects when built are solely for a single platform, usually the same as the development machine they are being built upon. Only later does the idea surface to maybe ship to another console, handheld or platform which then highlights issues in the games implementation that can lead to issues.

You CAN just build and ship to one platform, there is no issue with that, but if you are possibly considering more than one, plan ahead!

• Choosing your path
• Sharing the code
• Interfaces are your friend
• Code first for platforms
• Shared content
• Handling multiple content types
• Building the project with DotNet commands

Choosing your path​

If you create a MonoGame project for a single platform, you get a single project with a single content project, life is simple and your concerns are light.

Once you consider adding another platform, there are a few considerations to take into account, namely:

• How to share code that is common between all platforms.
• How to structure code that is common (e.g. achievements) but have different implementations on different platforms (e.g. Steam, Xbox, etc)
• How to manage code specific to platforms.
• How to share content that is common between all platforms.
• How to structure content specific to a platform.
• Do I also need to consider multiple styles per-device (high-res, low res), but granted this is also a consideration for single-platform games.
• Will I have enough hot beverages and snacks to keep my mind at ease through all this stress.
• Cats, if not my own, the neighbour's cat will wander in and steal all my code.

Granted the last is a bit of a fringe case but very dramatic when it happens, and for reference, this never happens with dogs as they just want to cuddle your feet or sit in your lap. "Just say'in".

It can seem a lot to take in, but let us walk through the major points step by step and then walk through generating our project (Click here to skip ahead if you like)

Sharing the code​

No one likes to write the same code twice, let alone, keep writing it or copying it multiple times across multiple projects, so when you are planning for multi-platform games, you need to identify any and all code which will be the same across all the projects (which is usually about 90% of your code) and then find a pattern that works for you to ensure you write it once, no matter the platform it is running on.

When it comes to sharing code, there are three patterns to consider, each with their pro's and con's:

Each of the options are easy to implement and run with, although Linked Files can become harder to manage the larger your project becomes, essentially because when you add a new class file, you have to remember to manually add it to all projects (or write a script to do so).

I Recommended to use a .NET Shared library for now unless you need UWP (Windows 10/11/Xbox Xaml), then use a shared library for now until the .Net8 upgrade.

.NET Class Library (Recommended)​

The recommended approach is to create a .NET class library and add a reference to that project to all your MonoGame projects, which is a quick and easy task. MonoGame even provides you with a project template specifically for MonoGame shared code.

*Note if you look at the references in the MonoGame Class Library project you will see the "DesktopGL" MonoGame reference. You can ignore this as it is just a shim, this is ignored when the project is built and the proper MonoGame DLL from your Game project is used instead. This is some magical wizardry performed by DotNEt during the build, much like the older MonoGame.Portable projects used to do.

To add a class library to an existing MonoGame project (assuming you have not created a Solution file already) is as follows:

Assuming you have a folder containing your MonoGame Project, e.g. MyGame -> MyGame.DesktopGL, while in the MyGame folder.

dotnet new sln -n MyGame
dotnet new mglib -o MyGame.SharedCode
dotnet sln MyGame.sln add MyGame.DesktopGL\MyGame.DesktopGL.csproj
dotnet sln MyGame.sln add MyGame.SharedCode\MyGame.SharedCode.csproj
dotnet add MyGame.DesktopGL\MyGame.DesktopGL.csproj reference MyGame.SharedCode\MyGame.SharedCode.csproj

Which creates a new solution file, adds your existing MonoGame project to it, generates a new MonoGame class library and adds that to both the solution and as a reference to your existing MonoGame project.

Alternatively, in Visual studio, simply:

• Add a new project to your solution.
• Select the MonoGame class library template.
• Right-click the references node in your Game Project and select a "Project Reference" for the new Class Library.

Repeat the last step for any additional MonoGame platform projects (just adding the reference) and all your projects now share the same codebase. Any code you add to the Class Library project are instantly accessible to all platforms and will be compiled with all platforms (and if any issues show up, it will instantly tell you).

P.S. Did you know you are NOT limited to just one class library, like content projects, you can have as many as you like if you prefer to also break up your code.

Adding a linked file​

First make sure the folder containing the linked code is located relative to the MonoGame projects you are sharing it with (usually all at the same level, e.g. MG Project 1, MG Project 2, SHared Code). This helps maintain the consistency of the code and links for your project.

Due to the lack of support for automatically adding linked files using the DotNet CLI tool, it is recommended to use Visual Studio (any edition, including community) to create and manage the links, to do this in Visual Studio you can right-click in the Solution Explorer to add an existing file (Add existing item), then instead of just clicking the "Add" button (which will copy the file), click the drop-down on the button and select "Add as Link" as shown below:

You will need to repeat this process for every class file you add to the shared folder and make sure to add it to each project. Usually, if you choose this path, I recommend building a batch script to do it for you. You will also have to perform this task when removing files.

To link files without Visual Studio, we need a PowerShell script to edit the csproj project definition and add the required XML for the linked file, the script I use is as follows:

# usage: .\Add-LinkedFile.ps1 -SourceProjectPath MyProject.csproj -LinkedFilePath ../Shared/mysharedclass.cs -LinkedFileName Shared/mysharedclass.cs -BuildAction Compile

# output: <ItemGroup><Compile Include="../Shared/mysharedclass.cs"><Link>Shared/mysharedclass.cs</Link></Compile></ItemGroup>
param(
    [Parameter(Mandatory=$true)][string] $SourceProjectPath,
    [Parameter(Mandatory=$true)][string] $LinkedFilePath,
    [Parameter(Mandatory=$true)][string] $LinkedFileName,
    [Parameter(Mandatory=$true)][string] $BuildAction
)

$sourceProject = [xml](Get-Content $SourceProjectPath)
$linkedFileRelativePath = (Resolve-Path -Path $LinkedFilePath -Relative)

$itemGroup = $sourceProject.CreateElement('ItemGroup')
$sourceProject.Project.AppendChild($itemGroup)

$linkedFile = $sourceProject.CreateElement($BuildAction)
$linkedFile.SetAttribute('Include', $linkedFileRelativePath)
$itemGroup.AppendChild($linkedFile)

$link = $sourceProject.CreateElement('Link')
$link.InnerText = $LinkedFileName
$linkedFile.AppendChild($link)

$sourceProject.Save((Resolve-Path "$SourceProjectPath").Path)

You then simply run the script "Within the folder of the project you want to update" to update the Platforms project to reference the linked file, for example:

From the folder "MyAwesomeGame/Platforms/MyAwesomeGame.Android" (assuming you save the above script in the MyAwesomeGame folder), and your shared code is in a folder called "Shared", also within the MyAwesomeGame folder:

../../Add-LinkedFile.ps1 -SourceProjectPath MyAwesomeGame.Android.csproj -LinkedFilePath ../../Shared/mysharedclass.cs -LinkedFileName Shared/mysharedclass.cs -BuildAction Compile

Which, if you then edit the "MyAwesomeGame.Android.csproj" file, you will see a new addition to the project, as follows:

  <ItemGroup>
    <Compile Include="../../Shared/mysharedclass.cs">
      <Link>Shared/mysharedclass.cs</Link>
    </Compile>
  </ItemGroup>

Alternatively, you can simply add the XML yourself, so long as you conform to the XML standards for the csproj specification, for example, this is also acceptable:

<ItemGroup>
    <Compile Include="../../Shared/mysharedclass.cs" Link="Shared/mysharedclass.cs" />
</ItemGroup>

In the past when I have linked files this way, I will build up the majority of the code within a single platform and then move that folder out and link the files, saves repeatedly doing this in the beginning.

Adding a Shared Library​

The shared library approach is much like the Class Library approach, except it uses the MonoGame Shared Project template instead. However, you cannot add a Shared Library to your project as a reference through the DotNet command-line (as it is a Xamarin solution), it is only supported through Visual Studio.

The only advantage today of using a Shared Library instead of a class library is that it also supports UWP (windows 10/11) projects. This limitation should be removed with the upgrade to .NET 8, but at the time of writing, this support is missing from Class Libraries.

Interfaces are your friend​

If you are not aware of Interfaces in the C# language, they provide an "example" of what a class "should" do for your project, and you can decide later which class that implements the interface that is used. It is a handy way of effectively swapping out which code does what, so long as each version implements the same interface (as the same public properties and methods of the interface).

In short, if I define an interface as follows:

    public interface IAchievementService
    {
        bool IsInitialized { get; }
        void Initialize();
        void UnlockAchievement(string achievementName);
    }

And then define two implementations of the interface, one for Steam and one for Xbox:

    // Steam
    public class SteamAchievementService : IAchievementService
    {
        private bool isInitialized = false;
        public bool IsInitialized => isInitialized;

        public void Initialize()
        {
            isInitialized = true;
        }

        public void UnlockAchievement(string achievementName)
        {
            // Do Steam Unlock Achievement Stuff
        }
    }

    //Xbox
    public class XboxAchievementService : IAchievementService
    {
        private bool isInitialized = false;
        public bool IsInitialized => isInitialized;

        public void Initialize()
        {
            isInitialized = true;
        }

        public void UnlockAchievement(string achievementName)
        {
            // Do Xbox Unlock Achievement Stuff
        }
    }    

Finally, in your shared game project, all your code simply uses a variable for the "AchievementService", knowing it has a property for "Initialised" and two methods to Initialise the achievement service or grant an achievement:

    public IAchievementService TheAchivementService

Then in each Platform project, they simply declare which service to use, and if you want to "AT RUNTIME" you can even swap them out, the shared code is none the wiser and in fact, DOES NOT CARE which service is it using for achievements, it just uses what it is told.

Pretty neat, eh!

Summing up interfaces​

Interfaces allow you to put MORE into your shared code library, letting you put either Platform specific implementations only in a single platform, or have multiple variations of an implementation available to swap out, e.g. A heavy attack or a light attack for instance. There are no limitations (other than all Concrete implementations MUST implement all the definitions in the interface).

Code first for platforms​

Having shared code makes it far easier to define a specific platform's own implementation, as it will only be contained within the platform project (as if you were building a single platform game), this includes the references and dependencies for that platform, which do not interfere with other platforms. It also means you do not need to have pre-compiler definitions scatted through your code to #IFDEF this or this. (which can become a real nightmare).

The short of the long in this case, is this:

• If the same code will run the same on all platforms, then put it in the shared library.
• If the code will ONLY EVER run on a single platform, put it in the platform project.
• If you are unsure, then use an Interface (see above) and decide later.

Shared content​

It is possible to have a shared content project that is used by all projects. This is not to say it is the SAME project, but rather, at compile time, MonoGame will build the project for just that platform as a separate thing.

Originally in XNA and earlier versions of MonoGame this was possible through a separate Content Project, but with the move to DotNet and .NET6, it is a little different as we need to manually create it.

The recommendation from the MonoGame team is to use separate Content Projects for each platform, to ensure compatibility and that logos and icons specific to a platform DO NOT get mixed up. But personally, I believe there is a halfway house, where "some" content can be shared and platform specific content can still live only in the specific projects.

To create a "content project" in the new DotNet land, you can either:

• Just create a folder, move an existing ".mgcb" definition into it and effectively "link the file" as a "MonoGameContentReference" build type (which works, but you will not be able to use the mgcb editor with it as it is technically not supported).
• Create a MonoGame Class Library, add a reference to the "MonoGame Content Builder Task" dependency to it and then add the remote link (which has the advantage that the content project CAN be edited within the content project).

Handling multiple content types (High-def/low-def)​

Most developers do not realise that you are NOT limited to a single content project, you can in fact have as many as you like, or alternatively, maintain separate project definitions (csproj) which are identical except they use a different content project for each.

Why would do this? Because if your project ships on multiple devices that support different resolutions, like Xbox and Mobile, the source content (albeit similar) will have different requirements, e.g. High quality 4K textures on Xbox and 1k or low-res textures on mobile (put a 4k texture on some mobiles and they will just die).

There is no hard and fast rule about which approach to take, and in fact, some developers ship BOTH types of content in a single project if it is small enough, but remember, the size of the content will affect the size of the final output, and it makes sense to keep downloads as small as possible for any platform.

The choice is yours:

• Ship all content to all platforms:
• Build out your game and swap WHICH content project gets compiled with which platform (or build, because Android)
• Have separate project definitions for each "build type" (high-def/low-def), each pointing to different content projects.

Building the project with DotNet commands​

Following on from the above, what follows are the set of commands that will generate a cross-platform project with the following setup:

• A root folder for the Game Project with a Solution file.
• A folder for a class library to share common code
• A "Platforms" folder for all the individual MonoGame projects
• All references "wired up"
• Separate Content Projects for each platform (you can create a shared one later if you wish and add their references.)

Script as follows:

dotnet new sln -n MyAwesomeGame
md Shared
md Platforms

dotnet new mglib -o Shared\MyAwesomeGame.Shared
dotnet new mgandroid -o Platforms\MyAwesomeGame.Android
dotnet new mgdesktopgl -o Platforms\MyAwesomeGame.DesktopGL
dotnet new mgios -o Platforms\MyAwesomeGame.iOS
dotnet new mgwindowsdx -o Platforms\MyAwesomeGame.WindowsDX

dotnet sln MyAwesomeGame.sln add Shared\MyAwesomeGame.Shared\MyAwesomeGame.Shared.csproj
dotnet sln MyAwesomeGame.sln add Platforms\MyAwesomeGame.Android --solution-folder Platforms
dotnet sln MyAwesomeGame.sln add Platforms\MyAwesomeGame.DesktopGL --solution-folder Platforms
dotnet sln MyAwesomeGame.sln add Platforms\MyAwesomeGame.iOS --solution-folder Platforms
dotnet sln MyAwesomeGame.sln add Platforms\MyAwesomeGame.WindowsDX --solution-folder Platforms

dotnet add Platforms\MyAwesomeGame.Android\MyAwesomeGame.Android.csproj reference Shared\MyAwesomeGame.Shared
dotnet add Platforms\MyAwesomeGame.DesktopGL\MyAwesomeGame.DesktopGL.csproj reference Shared\MyAwesomeGame.Shared
dotnet add Platforms\MyAwesomeGame.iOS\MyAwesomeGame.iOS.csproj reference Shared\MyAwesomeGame.Shared
dotnet add Platforms\MyAwesomeGame.WindowsDX\MyAwesomeGame.WindowsDX.csproj reference Shared\MyAwesomeGame.Shared

Once complete, you should have a solution which looks like this:

The only final changes I would make would be to either:

• Delete the Game1.cs from the class library - OR
• Remove the Game1.cs from each of the platforms and then update the respective launchers (e.g. program.cs) to start the shared Game1.cs on start.

Depends if you also want a common Game class or not to begin your game, it is up to you and there is no "wrong" answer.

Additionally, you can delete the "Content" folder from the class library as it is extremely unlikely you will use it.

Summary​

Whether you build your project for a single platform, or consider the options of maximising your reach by adding more platforms to deliver to is a very important decision. It does not come without a small amount of additional risk, but the rewards mean MORE users playing your game on more platforms.

In most cases, everything will "just work", that is the beauty of MonoGame. On occasion you will hit an issue with a dependency or service that is particular to a specific platform, which you then need to address in isolation, ideally not affecting other platforms, it is a fine balancing act.

But with shared code, your life is made that much simpler as you get to update all platforms at once with central changes, taking feedback from multiple players with different needs to wholly make your game better (or drive you to insanity with their endless demands).

Whichever path you take, I wish you well on delivering on your dreams.

TL;DR -> MonoGame rocks and continues to be one of the best open-source frameworks for building games including with lightweight editors like VSCode, on ANY platform.

Things are busy and heating up in the Open-Source development space and the MonoGame Team announced their plans to step up to the recent demand.

And as was pointed out to me on the new MonoGame Content Request board that I helped to setup, a fair few developers are asking how to get started. The Videos I did a short while back are still good, but do need modernizing for the latest release and beyond.

A Guide for Setting up VSCode for MonoGame on Windows/Linux/Mac

Kicking things off, right at the beginning, here is a guide to getting started with VSCode for MonoGame. And thanks to VSCode, FINALLY, the instructions are the same for ALL PLATFORMS.

• Starting Fresh
• Installing the Extensions
• The .NET SDK
• Installing MonoGame and creating your new game!
• MonoGame, Start!
• Build and Test
• The Content Pipeline
• Debugging

Starting fresh​

To keep things clean, all the instructions here are run from a clean machine, however, if you already have some parts installed, they will be automatically updated, thankfully.

Simply visit code.visualstudio.com and get downloading Visual Studio Code, the drop down button on the left should auto-detect your operating system, or you can click the down-arrow to show the list of platforms to choose from.

One Editor for multiple platforms, including the Web (as in VSCode for the Web on GitHub), however, as far as I know, the web version does not support .NET building at this time.

Installing the Extensions​

Now, MonoGame as of 3.8.1.303, is a .NET Runtime framework, this vastly simplifies its installation and use because all aspects are now unified and everything you need to build your games is all built into the .NET SDK.

If you open up VSCode after its installation, you should be presented with the above screen, welcoming you to a new world of light, development and if the mood takes you, fun.

But as it stands right now, you only have a fancy text editor (granted a very powerful text editor), where VSCode really comes into its own is with "Extensions", for which there are extensions for just about any programming language going (within reason, there is no assembly editor, yet). Extensions add things like:

• Compilers for building.
• Intellisense for code suggestions.
• Viewers for specific file types.
• Language understanding and formatting.
• And so much more.

For MonoGame we need two things, the C# Dev Kit (which includes the C# language and some other tools) and the .NET SDK.

Starting off, click the {} in the left-hand toolbar and then search for "dev kit" which should then result in a whole list of extensions and right at the top (hopefully) you should find the "C# Dev Kit" published by Microsoft, as shown below:

Click on the blue "Install" icon (as indicated in the image) and off it goes.

Some extensions require you to "reload" VSCode after installing/uninstalling, if it does, the Install button will finish with a "Reload" button, click it and VSCode will restart right back where you were as if nothing changed.

The .NET SDK​

The .NET SDK (if you are not familiar with it) is simply the latest generation of the .NET Framework SDK, as ever it is backwards compatible and for MonoGame we need at least the .NET 6 SDK (until it upgrades to .NET8).

Thankfully, the .NET SDK is backwards compatible with previous versions, so installing the current version -- at the time of writing --, the .NET 7 SDK, will still enable you to develop with MonoGame.

With the "C# Dev Kit" installed, we get a bunch of new commands to use in Visual Studio Code, which can be accessed by pressing:

This will open up a bar at the top of the screen with a bunch of commands. It also includes a handy search feature (because there is a command for almost anything), so if you type ".NET", you should see the following:

If you do not already have a .NET SDK installed, you will be greeted with a nice prompt / warning Window, as shown below:

Which is simply informing you that you have something else to install to begin, this is not a VSCode extension and like .NET Framework installers previously, is not something you install in VSCode, but into your system instead. So, click on the "Get the SDK" link (which will open a browser) and you can then download and run the latest .NET SDK installer from there.

> You should also close VSCode at this point, to ensure everything is clean and ready for your return!​

Click Install and follow the instructions (if any) to complete the setup to proceed.

Ok, so you have all the prerequisites installed, what now? Well, we start using MonoGame!

Installing MonoGame and creating your new game!​

Let us begin by starting up VSCode again, we get the familiar screen, but not much has changed, we are simply prepared and ready to actually begin using MonoGame, we have the tools so let us begin!

Welcome to the Terminal screen, you will be spending quite a bit of time here. I have often heard that some developers miss a GUI at this point and it is a fair quip, however, The is great because it is the same process on ANY platform, and you may find it more comforting, with the same tools, the same commands and likely the same coffee!

Start up the Terminal Window using the above menu and you will be presented with a Terminal/command-line window ready to process your commands, as shown below:

From here, we are simply following the steps laid out in my previous article and in the MonoGame "Getting Started" guides, first type the following to install the MonoGame DotNet project templates:

    dotnet new --install MonoGame.Templates.CSharp

And you should see something like the results below:

I did note in testing that the .NET 7 SDK no longer needs the -- (double dashes) before the "Install" argument, but in a good and true backwards-compatible fashion, it still works. But I leave it in all instructions as it is still needed if you are using the .NET 6 SDK.

The highlighted parts are the template IDs which you need for creating new projects, so keep an eye on them for reference.​

With MonoGame installed, we can get on with starting our new project!

MonoGame, Start!​

From now on, when you need a new MonoGame project, this is where your journey begins, your machine is setup (unless you paved it recently or are borrowing someone else's) and everything is ready. The steps for creating any new DotNet project are always the same:

• Create a new Folder.
• Run the DotNet new command.
• Done / Open the folder in VSCode.

I personally these days find it easier to stay within VSCode and do it all from there, but the choice is yours.

To perform this in VSCode, using the "Terminal" window you used to install MonoGame, check the directory you are in (as indicated by the left hand side of the cursor which always shows you where you are, handy eh?), and then navigate to where you want your game created and make a new folder, e.g. :

cd C:\Development
mkdir MyGame
cd MyGame

or you could swap out to your explorer/finder and do it, the result is the same.

Now, using the Terminal window IN the folder (if you used a GUI, you still need to navigate there in the Terminal, hence why I say it is easier to just use the Terminal), you then simply use the following command:

dotnet new mgdesktopgl -o MyGame

Which is comprised of:

There, you now have a new MonoGame Project built and ready to use, including the MGCB content tool, it is no longer a separate install, it is built into the project itself. (I can imagine how many hours that will save me managing it separately).

All that is left is to "Open the Folder" where you created the project (the folder WITH the .csproj file in it, not its parent folder) in VSCode and off you go, editing in VSCode on the fly!

Build and Test​

Like Visual Studio, all the building of a MonoGame project, no matter which platform it is, is performed by the MS Build tools, but again, thanks to the latest .NET frameworks, this is all managed by a simple command:

dotnet build

This compiles and checks your code can build, it also restores any tools, downloads any dependencies for the project, since it was last run; all in one. What you get, assuming it is successful, will be a folder structure like this:

    MyGame\bin\Debug\net6.0

Comprising of:

In the final folder, you will find an executable of the same name as your project (MyGame.exe in my case on Windows, it will be different for other platforms) which you can run.

To create a FINAL build (because you do not want to ship debug code to customers, do you?) you simply follow the steps in the MonoGame documentation and produce a "published" build, as follows:

    dotnet publish -c Release -r win-x64 /p:PublishReadyToRun=false /p:TieredCompilation=false --self-contained

Which basically commands MSBuild to generate a Release build, ready to publish and makes the output the best it can be.

If you want to read more about the "dotnet publish" command or other dotnet commands, check the official Microsoft documentation.

Done, dusted, all there is to say, is it not?

The Content Pipeline​

Now, if you have read any of the documentation regarding MonoGame, you will know there is a tool for Managing / Building content separate from your project to help with compiling your project (as well as a whole bunch of other platform optimization and wonder). You do not have to use it if you do not want to, but I always recommend using it because I always liked it.

Previously, you had to install the tool separately, find a way to launch it beyond the command-line which "mostly" worked for Visual Studio, but thanks to VSCode Extensions, there are already two extensions for adding a "right-click" launch ability for the MGCB tool directly in VSCode (sadly only one works, but here is hoping the dev fixes it).

To install the extension, simply go to the Extensions view (as before) and search for MonoGame and you should see a list like the one shown below:

From my testing, only the second item (the one with the STARS) actually works, so feel free to install it if you wish. Once complete you will be able to open the MGCB tool by right clicking the ".mgcb" file located in the "Content" folder.

> *Note, you have to have built your project AT LEAST ONCE for the mgcb tool to be installed for your project. The tool is no longer global, which allows you to use the version SPECIFIC to your project and avoids conflict issues between versions.​

Alternatively, you can always run the following in the Terminal window for your project:

    mgcb-editor Content/Content.mgcb

Debugging​

VSCode also has the ability to debug .NET projects in the same way that Visual Studio can, just in a slightly different way, however, it is not on by default, you have to enable it.

To setup debugging, open the Command Palette using

Once open, type the search criteria "Generate" and locate the .NET Generate Assets for Build and Debug command and click it (or hit return/enter) as shown in the image below:

This will generate the necessary "Launch Configurations" in VSCode and store them in a new ".vscode" folder in your project (do not ignore this folder if you are customizing debug/launch options in VSCode)

With that setup, you can begin to run your project in Debug mode as follows:

• Navigate to the Debug view using the Play Arrow button on the left hand side (as indicated in the below image).
• Change the "Run and Debug" mode to "C# <your game name>" using the drop down button. (next to the cog icon).
• Click on the green Play icon (as shown below) next to the "Run and Debug" selection.

Now your game will run as normal with VSCode attached and you can Debug/BreakPoint/Catch Exceptions like the best of them.

Check the official VSCode documentation for more information for debugging with VSCode.

Summary​

We have come down a long road, one that is far shorter to actually do than it was to write or even read this post. Hopefully it will help the newcomers and prepare everyone for what is to come!

Now I'm going back to the drawing board to work on more stuff, laters!!

P.S.

If you have an idea or a question that you believe would require a tutorial, visit the MonoGame tutorial series suggestions project board, and if you do not see your idea listed, then Create your own request here. All the creator community is watching and looking for your requests.

TL;DR -> MonoGame rocks and continues to be one of the best open-source frameworks for building games.

Making games is hard enough (or the most fun you will ever have) without the worry of the Framework or Engine you use either being cancelled or changing the terms of its use in the future, which can provide uncertainty for the years of effort you put into making your dream a reality that everyone can play.

Whether it is an open-source project or a paid development solution, it is hard to choose the right option that will ensure your investments are secure.

Thankfully there are quite a few engines and frameworks available today that do fit that bill:

• They have been around for many years.
• They are open source or give you access to their code. (Ensuring if they did disappear, you still have what it takes to build).
• Have a growing community ready to help at a moment's notice.

The Framework of discussion today is MonoGame, which despite all talk to the contrary is very much alive and well.

• What is MonoGame?
• What is the MonoGame Framework?
• Where is the MonoGame Community
• What is the MonoGame toolset and getting started
• MonoGame Extensions

MonoGame​

MonoGame is a game development framework born from an implementation pioneered by Microsoft around 2004 called XNA (no acronym), it brought the dream of building games for Windows and Xbox (and later phones) using C#, it was a breath of fresh air and made programming games a breeze. Sadly, XNA was discontinued by Microsoft but was reborn as MonoGame.

XNA had made such an impact, that the community was just not willing to let it go, and today it flourishes.

Now, MonoGame is a Framework (not an engine) and its power lies in the original XNA implementation that abstracts (hides) the underlying complexity for making code, graphics, sound and the myriad of other technologies required to run a game on a multitude of platforms. Which means that you code your Game once and then you can run it on any of the platforms that MonoGame has an implementation on (much like how Unity / Unreal and GoDot work today, but arguably XNA did it first for C#).

In basic terms, you write your game using MonoGame's implementation and it then generates a project to deploy on your target platform.

Contrary to some writers beliefs, Like the swan on the lake, there may not seem much movement on the water, but underneath, there is furious paddling going on to keep it moving.

P.S. I tried to find an appropriate GIF to demonstrate this and failed, for that I am sorry. The best I could find was a worried cat learning to swim :S.

The MonoGame Framework​

One thing that keeps coming up from time to time, and sometimes confused with "MonoGame is Dead", is that the XNA implementation used in MonoGame (the language and structure) has not changed for years, which is very true (much like a car has 4 wheels, doors and an engine), the "front end" of MonoGame, for the most part, has remained the same since XNA 4.0 (the last iteration of XNA). This is not to say nothing has changed, but rather it has remained stable and secure, what you wrote 10 years ago, will still run today (with the obvious caveats for minor critical changes).

Where MonoGame evolves is all the hard work and underpinnings to MAKE your game run on all the other platforms, handling the complexities for how Audio works, how graphics are drawn to the screen, and the vast technologies involved for different devices on a multitude of platforms. This is no mean feat as vendors are constantly updating, changing and maintaining their platforms and "just expect" developers to keep up or be left out in the cold.

So as MonoGame evolves YOU DO NOT NEED TO CHANGE YOUR GAME, what you have written and the MonoGame features you use will continue to work, it will just work differently on the target platform when it is eventually compiled (built).

In fact, MANY of the original XNA Game Studio 4.0 samples and code STILL WORK today, that is how strong MonoGame is! Check it out for yourself from the XNA Game Studio Archive

Just be aware, that XNA 1, 2 and 3 samples WILL need updating to XNA4/MonoGame to actually work (it is not magic after all).

This is not to say you never need any vendor platform code at all in your project (MonoGame cannot build for EVERY feature), for instance, if you want to use Apple's notification system and Google's notification system in your project, you will still need to handle that, but thankfully C# makes that easier with platform dependent code (again, much like how other engines/frameworks do).

The MonoGame Community​

The MonoGame community is VAST, and as previously stated, most XNA/MonoGame books that have been written since 2010 will still continue to be valid and worthwhile (now find me an engine/framework that can say that). About the only thing that has changed (due to the underlying features mentioned above) has been how you install MonoGame and how you build with it, but more on that later.

Amongst MonoGames community weaponry it includes:

• A very active community site for Questions, Answers and showcases
• Loads of official and supported community sites
• Lots of articles full of useful tips from Community members
• An active Discord site with tons of threads to choose from
• (My favourite) The entire catalogue of XNA samples and MonoGame content all preserved on GitHub
• Awesome-MonoGame - A MASSIVE list of MonoGame resources which is continually updated (5 Hours ago at the time of writing, in 2023 no less)

And so much more, since any XNA content is also valid (from the coding side) and about the only real difference from the XNA days is how the content pipeline is used (which is totally optional).

The MonoGame Toolchain​

The MonoGame toolchain has gone through many iterations since its first release, always moving with the times and updating to modern technology, from Separate plug-ins to Visual Studio extensions and in the past year, updated to use the .NET Runtime and toolset. with each iteration, the API remains the same, so existing projects are not broken, but under the hood, things keep advancing.

And MonoGame does not stop there, still planning ahead and looking further into the future as technology evolves, talk is already well underway for a .NET 8 upgrade which brings even more cross-platform capabilities and (if reports are true) faster compilation and execution (your game goes faster). There is even talk that with the next .NET upgrade, tools such as BRUTE (which provides C++ compilation to some AOT native platforms, such as Switch) could even be retired. (depending on the capabilities published by Microsoft)

For today, MonoGame 3.8.1 (and beyond) are all based on the .Net Runtime and getting started is as simple as:

1. Install the latest .NET 6 SDK (comes with Visual Studio if you have it).
2. Install the MonoGame templates - dotnet new --install MonoGame.Templates.CSharp from the command-line.
3. Create a folder for your Game.
4. From the folder, create a new MonoGame project for your target platform, for Desktop OpenGL - dotnet new mgdesktopgl -o MyGame
5. You now have a new MonoGame Project, go build your game.
6. When you are ready, simply run dotnet build to create a build for your game and then run it.

For more details on getting started, check out the documentation

Extending MonoGame​

One of the biggest confusions and usually the reason commentor's state that MonoGame does not change is because it does not change from the outside. The MonoGame team persevere to ensure the API for MonoGame retains its XNA origins. It does not change for a reason, and thanks to that, games written yesterday will continue to work today (and beyond).

MonoGame does however encourage and support community members building ON TOP OF MonoGame to further extend it and then helps to then promote those extensions for other MonoGame users. These can range from simple addons, to full-extending frameworks, even to engines built on MonoGame. These Engines make full use of MonoGames platform capabilities to ship a game and focus on the parts they need to deliver an engine.

Some of the biggest out there include:

• MonoGame.Extended - If MonoGame doesn't do it, then MonoGame.Extended extends it (pun intended).
• FNA - Not technically a MonoGame extension, more of a MonoGame competitor, but highly worth a mention, even admired by the MG team.
• FlatredBall - A full-featured game development platform built on MonoGame.
• TiledSharp - A fan of using the Tiled editor for your 2D maps, then easily take those maps into your MonoGame project. Although I do see this project is no longer supported, at my last run it still worked very well.
• Many Many more (your name here).

It is funny that most engines feel the need to build up an asset store for content, but with MonoGame, GitHub is its asset store for all the things you need to extend your project. As for content, that is accessible from almost anywhere and most of it is either natively supported by MonoGame, or "there is an Extension for that".

Content Management​

One of the interesting capabilities that came from XNA originally, was the idea that you could have a "Content" (asset library) project, build your assets separately to your code and live happily. In fact, many competitors to XNA scoffed at this and said it shouldn't have bothered, yet today a lot of developers complain about how long builds take in engines because of content and look for ways to separate it.

MonoGame took the Content Project base and built its own MonoGame Build Tool which focuses on content and adds extensibility (much like XNA) so you can write custom importers and processors to handle different types of content. You could even write your own custom level design configuration and have the entire pipeline process and generate your levels for you. I am a big content pipeline fan and have written and shared many extensions for the Build Pipeline in the past.

However, one of the biggest myths (or debates depending on where your sticks land), is that this was the ONLY way to have content in MonoGame, which is simply NOT TRUE. If you want, you can ignore the whole MonoGame Content Builder and just load content/assets and such manually in code.

MonoGame will never seek to limit you in any way.

So whether you are a content pipeline user:

    var myTexture = Content.Load<Texture2D>("ball");

Or a non-content pipeline user:

    using (var fileStream = new FileStream("test.png", FileMode.Open))
    {
        var myTexture = Texture2D.FromStream(GraphicsDevice, fileStream);
    }

The path is yours and MonoGame will never dictate or tell you how to build your game.

Summary​

This post has wrangled on for a while trying to set a few truths alongside the doubters or nay-sayers who call something dead because they don't see change happening.

Full disclosure, I have wondered the same because it sometimes takes a long time between releases. But I work with the team, who are equally frustrated at times and things are ALWAYS in motion.

Given no one gets paid to build MonoGame and all the supporters work in their spare time, rather generously I might add, it is still amazing how much love MonoGame gets. But to those who still and continue to MonoGame, I salute you!

In times of upheaval, you might want to give it a whirl, load up a tutorial and try building something and it is indeed surprising how easy it is. Even without an editor/GUI to lean on, it is amazing how visceral and close to the metal MonoGame feels. Every pixel that moves, every change that happens is directly under your control and it is surprisingly freeing.

Laters.

(Comments welcome!)

TL;DR -> Jekyll builds can have page collisions in different places if the pages happen to have the same title. Skip ahead to fix!.

WOW, it has been a while since I last posted, which is genuinely very bad for me, not to say I have been lazy or up to no good, quite the opposite, I have a myriad of things on my mind:

• This year I have been writing a new book Accelerating Unity Through Automation
• I changed jobs due to a sudden and dramatic change in events.
• Had to setup my own company (again) for contracting, as work involves companies across the pond from me.
• The Reality Toolkit and its new companion the Service Framework have kicked up a gear.
• Various OpenSource and related activities online which drown my soul.
• Kids, family, dogs, puppies and more.

Personally, I do not see this as a valid excuse, but I have been slowing down a bit of late due to my progress in time, promises made and broken to myself, but C'est la Vie.

Back on target - broken links in Jekyll​

So why the sudden post. Well it all started when.. No it's too much, let me sum up.

In short, when posting about my new book, one favoured visitor informed me that all the book links on my blog site were no longer working. I was curious, bemused, confused and above all, frustrated.

I had migrated my blog some time back and despite my best efforts and mad "search and replace" skills, I still find the odd link broken. Not put off I checked out (what I thought) the page that had the information, except, the links were all fine.....

Confused, yes I was.

Updating the blog site​

So in an effort to resolve this I tried a few things:

• I tweaked and pushed the offending page to the blog and published - no effect.
• I deleted and re-added the page - no effect.
• I deleted the github pages deployment and republished using the new actions method - no effect.
• I toyed with the idea of deleting the site and republishing - I DOD NOT DO THIS.

In the end I went back to basics and tried building the site locally, only to find all my test setup no longer worked, I fixed that and built the site.

What I found was something I did not expect:

CONFLICTS​

Jekyll page collisions​

Only when building locally do these kinds of conflicts how up, the GitHub Pages deploy actions all report SUCCESS!!!.

I did dig deeper much later, the older "pages build and deployment" publishing task does NOT show any errors, however the newer GitHub Actions based deployment DID actually show the same error (if you know where to look)

What is essentially happening is this:

• There is a prebuilt HTML file called Books.html which by default deploys to <root>/Books.html (the file I was editing)
• However, there was also a post called 2014-09-02-books.markdown, which when built is written to <root>/books.html.

Jekyll strips the dates from posts when generating the HTML.

So two files ended up writing to the same output file, and basically, the last one to process won (the blog post version) as a Jekyll build will keep writing and just let you know what it did.

Fixing collisions​

Laughably, the only way to prevent the collision was to delete one page or the other, or rename them, that is all there is to it.

INCLUDING THE SUBJECT MATTER AT THE TOP OF THE FILE!!

So once again my blog is a happy place, links work and pages are showing exactly how I expect them to be, phew. Only took an hour of pulling hair out.

You must read from the book​

I almost find it ironic that one of the things that would have helped the solution was to read my new book, which is due to go on sale very soon (or now if you are reading this in the future).

if you want to learn and understand automation and all the joys that come from letting someone else to the repetitive parts of you job, then I would recommend a read.

And if you attended my talks on Automation recently, you could try all the fun things you can do with automation too.

I hope this helps out any other Jekyll blog users and save you from a certain amount of hair pulling in diagnosing issues on your blog.

P.S. Switch to the new GitHub actions build and publishing, it is much better​

Managing automation is hard enough without having to pollute your git history with changes to your actual workflows, in reality, the workflow itself is unlikely to change but there can be subtle updates in what each workflow action needs to do.

As an example, in the Reality Collective we needed to change the versioning strategy for our packages due to upcoming changes in Unity (another nightmare to be sure), the actual flow is not changing but we simply needed some minor updates. All this required (although not in reality) was to update our automation to change the "Preview" tag we previously use to "Pre". Now, if we had all the code and scripts inside our actual projects, this would have meant changing ALL the packages in all the projects we deploy for this one minor change, however, we had employed "Reusable workflows" in all our automations previously, so we could make the changes in a separate repository rather than pollute our core code projects. (well, at least in theory).

What are Reusable workflows​

Reusable workflows come in several forms, the most common are the Published "Actions" on the GitHub Actions marketplace, such as the popular "Checkout" action to clone code at the beginning of an automation. Actions are reusable scripts that can consumed in your workflow.

But what if you do not want to publish your workflows to the public marketplace? Well, that is where Reusable Workflow repositories come in, like Actions, they are workflows published to a GitHub repo and can be accessed from any other implemented workflow with a few "security" limitations:

• The repository the workflow files are located must be public.
• The repository must exist in the SAME organisation as the repositories that want to consume them. (No cross org access)
• It must be a full repository, no forks allowed.

See the GitHub Blog article on the launch of Reusable Workflows

As an example, here are all the reusable workflows the RealityCollective publishes for all its packages to consume:

Reality Collective reusable workflows

By default these can ONLY be consumed by other Reality Collective repositories, to use then in other organistions they must be manually copied and maintained.

To actually share them, they would each have to be converted in to Marketplace Actions, but we have no need at this time to do that.

Consuming these workflows is easy by having the following Job definitions within the actual workflows in each of our packages, thus:

  release-Package-only:
    name: Release package only, no upversion
    uses: realitycollective/reusableworkflows/.github/workflows/tagrelease.yml@v2
    with:
      build-host: ubuntu-latest

The workflow is called using realitycollective/reusableworkflows/.github/workflows/tagrelease.yml, specifying the organisation, repository and location of the reusable workflow file, followed by a TAG or Branch to source the pipeline from.

I would strongly advise AGAINST using branches as they can be more trouble than they are worth, see below.

Managing the workflows​

Now, obviously over time these workflows need to be maintained and new versions added/updated/removed but you do not want to be changing all the repositories consuming them constantly, hence why reusable workflows require a branch or tag suffix against the reusable workflow file.

And this brings us to why this article exists today, as the public actions GitHub publish have some subtleties that are not immediately obvious and what follows is a guide to managing your own reusable workflows.

1. Once your workflows reach a stable state, create a MAIN VERSION Tag for the release of the workflow. E.G. V1.
2. With the first changes you make, once stable, create a new Sub Version Tag for the incremental release. E.G. V1.0.1.
3. NOW, you need to rebase the MAIN VERSION Tag to match the new Sub Version. E.G. Delete V1 and recreate using the same commit as V1.0.1.

If you wish you can create automation for your workflows to automate the tagging for the reusable pipeline repository.

This ensures that all workflows using the V2 tag will get the latest update automatically. Only if there is a breaking change in parameters or flow, should you then do a Major version update to V3.

This subtlety with rebasing the Major Tag to the new commit is what eluded me in maintaining our workflows recently, so hopefully this will shed some light for you too, if you are using reusable workflows.

Making your own reusable workflows​

As a simple guide for making your own reusable workflows for your own repositories, here are some times to avoid some of the pitfalls I faced when building our first batch:

1. Create a new repository in your organisation solely for Reusable Workflows, the name is not important but make it recognisable.
2. Make the repository Public (until such time that GitHub allows us to have private reusable workflow access).
3. Create, test and validate your first batch of workflows, test in other repositories using the "Main"" suffix (or the name of the branch used for testing).
4. Once the workflows are Stable, create a Release commit to define a release point in your repository.
5. Create a new Tag (V1 for example) for the release.
6. Create a Release from the Tag for reference to document the release and what is contained.
7. Apply real workflows using the new Release tag (@V1)

Note changing any workflows in the repository now will NOT BREAK any use of the workflows, making life more stable.

Updating your workflow​

When you need to make changes and create a new reusable workflow release, plan it, test it and update as follows.

For a minor release​

1. Make changes to the repository, either in the default branch or a separate one (should not matter)
2. Once stable, create a Release commit to mark the release.
3. Create a new minor release tag for the release (e.g. V1.0.1)
4. Delete and recreate the Major release tag for the release (delete V1, recreate under the same commit)
5. Both the minor release and major release tags should now be the same
6. Create a Release for the new minor release version.

No changes are needed to existing workflows as they will use the new updated V1 commit as the source of their workflows.

If you do not recreate/update the Major release Tag commit, your workflows will not see changes unless you update them to the new minor release.

FOr a Major release​

1. Follow the same steps for a minor release, except you will only create a brand new Major release tag and Release. Previous version is untouched.
2. Update any workflows needing the new version with the new Major version number, e.g. @v1 -> @v2.

To use the new version, all workflows needed it will need to be updated.

Wrap up​

It has been a "not" fun time working through updating our pipelines recently, mainly because we followed the GitHub examples andd just use the Main branch (@main) which created headaches when we needed to make updates. After a few hours examining what GitHub does to manage its own workflows we built up the above flow (the Major Release re-tagging was the latest).

But now we have a flow for maintaining our workflows better and we can get back to fighting Unity instead.

Hope this helps.

With Azure Devops and GitHub Actions you have the option to either use their hosted agents using the Azure backend, which is fine as you do get a decent amount of time of free resource but eventually you are going to end up paying for the service. Or, you can host your own agents on your own PC or even a dedicated box just for building.

If you have spare kit (does not need to be uber fast) then it makes sense to leave it powered on in the corner and have all your builds/tests run on it while you continue to work. And this isn't an either/or moment either, if you want you can run some of the smaller automations you use to do code validation or check-in "checks" using hosted agents and then run your intensive work on your own box, it is completely up to you.

Microsoft-hosted pipeline agents​

As mentioned previously, for both Azure and GitHub automation, Microsoft provide you several images to run your jobs, which you chose is dependent on what the job is doing and the requirements needed to run them, for most script / .NET / NPM tasks Ubuntu (Linux) is fine and it is also the cheapest from an automation standpoint. As soon as you start needing software, such as Unity, then your options become a bit more limited to either Windows or Mac:

Make sure to check the previous articles for more details on using the hosted agents for either Azure Devops or GitHub Actions.

Self Hosting​

As the title of the article suggests, self-hosting simply means you are using your own hardware, be it physical or virtual (yes, if you have virtual servers hosted elsewhere, you can self-host on them too), you are in control of the setup, operation and runtime for the host. This can greatly simplify the runtime of your host and even your automation pipelines as you can skip the steps needed to setup and install required software because you already know it is installed (because you installed it), rather than having potentially complicated scripts to download and install each requirement on each run.

Fair warning, Unity is still a pain when it comes to automation, ever since they updated to the V3 of the Unity Hub, it has made installing / checking installs of the Unity Editor very temperamental. Personally, I manage the version of Unity that is installed manually now because automating it became too unreliable. Thanks Unity!

Requirements​

The requirements needed to run a self-hosted agent come in two parts, what you need to run your pipelines and what you need in order to run the agent itself.

Build Software​

What you need for building / automating and testing will largely depend on what you are building, for example:

• Unity Hub.
• Unity editor (version determined by your project), which must be manually updated when you upgrade.
• Visual Studio (community edition is still fine)
• .NET runtimes (usually installed with Visual Studio)

Automation Software​

For the automation, you will need scripting runtimes and also the agent software of choice, depending on whether you are using Azure, GitHub or even one of the other popular automation services, like GitLab (however, we are only covering Azure and GitHub in this article):

• Powershell or Bash, depending on your scripting language of choice. Personally, I use both.
• NPM (Node Package Manager) if you are intending to publish anything or manage the version of your packages. Also requires NodeJS.
• Agent software of choice. Azure / GitHub

You may find on your initial forays into automation that there may be other requirements needed depending on your workflows, just be sure to document them as required so that when you install another agent, you have everything recorded.

How many agents?​

One thing that some people miss, is that agents are virtual setups in themselves on your build machine and there is NO LIMIT to how many agents you can have installed on a single box. In my experience, I generally install approximately 3 agents on a PC, depending on how much I expect the agents to do and how intensive the operations are:

• If you are running small scripting jobs, then install more agents.
• If you are running intensive build and packaging jobs, install less agents.

Ultimately though, you can mix and match again. Have several small agents setup with a Tag/Name to identify them and then have one single agent identified as the BUILD agent for solely doing the big builds, then you can ix and match which are used in your jobs.

Personally, I setup about 10 agents for small script jobs and 1 (or 2) dedicated agents for just builds, this throttles the demand based on how intensive the jobs are likely to be and do not slow the build PC (Usually my main development pc) down too much.

Agent identity​

A critical thing for your agents is the identity the agent uses in Azure or GitHub, ideally this should be a dedicated and separate user, this is to ensure there are no mixups for the account running builds. You can use a personal account, but if that person leaves or resets their access tokens, you will have to recreate all your agents!

So create a new user in GitHub (it is free) and Azure (if also using Azure) and give it sufficient rights to access the parts of the project you want automated.

Agent Location​

One often missed fact with agents is where to put them on the build host, whether it is on Windows or Mac/Linux, you need to take in to account that the PATH that is build can get quite long! On Windows this can create issues, less so on Linux/mac but still something that has to be considered.

The "Rule of Thumb" I always use is to place the folder for the agent as high as possible (Root ideally) with short folder names, e.g.

• Create a single character folder on the Root of the drive, e.g. A (for Azure) or G (for Github), or as close to root as you can, for the agent type.
• Create a folder for each agent within the "Agent Type" folder, either as the name of the agent or simply 01, 02, etc. E.G. MyAgent-01.
• When asked for a "working folder", keep it short, ideally simply "w"

All in all, you want to keep the working path the agent uses as short as possible, to give enough path length for your builds, which as stated, can get VERY long in some cases.

Your final path should resemble something like:

• "c:\a\agent-01\w"

Setting up an Azure Agent​

Check the official MS docs here

Azure DevOps agents are quite robust and do take some practice to setup, the steps are as follows:

1. Create a new PAT (Personal Access Token) for the user running the builds.
2. Make a note of the Azure Organisation URL (e.g. https://dev.azure.com/myorganisation)
3. Navigate to the "Organisation" settings (as agents are created for the Organisation ONLY) - Organisation -> Organisation Settings -> Agent Pools
4. Create a new Agent Pool (if you do not have one setup already), the pool name is what is used on the Job.
5. Create a new Agent on Azure and download the latest agent software to the Build Host (just gives you the instructions)
6. Create a new folder for your agent, ideally with the index of the agent, especially if you are adding more than one. E.G. "myAgent-01", or just "01".
7. Extract the Agent software into the agent folder.
8. When asked, enter the Organisation URL (e.g. https://dev.azure.com/myorganisation).
9. For security, select "PAT" (just hit enter) and then copy/paste the PAT you created in step 1.
10. When asked for a "Working Folder", set this to "W" (it is just a short name).

Depending on the OS you are installing the agent on:

• For Windows, you will be asked if you want to run this agent as a service. If you want it to automatically start when the Host powers up, then select Yes and click enter to select the default user to run the service as.
• If you are installing on a Mac, you have to run a separate command to install the service which is ./svc.sh install and then ./svc.sh start

Personally I have always installed agents as Services so I do not need to think about them, else you will need to run a separate command each and every time you need to start them (which some people do), just check the Azure docs for more details for your Operating system.

You now have a single agent setup, repeat steps 6 - 10 for additional agents with a different agent folder name.

Setting up a GitHub Agent​

Check the official GitHub docs here

Setting up a GitHub Actions runners are far simpler that Azure agents, simply because they have less steps and are a lot more streamlined, however, they can still cause confusion.

1. Create a new GitHub PAT (Personal Access Token) for the user running the builds.
2. Navigate to the Organisation Settings in GitHub (as agents are created for the Organisation ONLY) - Organisation -> Settings -> Actions -> Runners
3. Select "New runner" and then "New self-hosted runner" to see the instructions.
4. Download the Agent software from the URL provided.
5. Create a new folder for your agent, ideally with the index of the agent, especially if you are adding more than one. E.G. "myAgent-01", or just "01".
6. Extract the Agent software into the agent folder.
7. Run the "config" command using the token SPECIFIED ON THE PAGE (not your PAT)
8. You will be asked for the PAT token as part of the install
9. You will be asked for any additional TAGS you want set against the agent, these are used to identify your agent in your Jobs. You can leave the defaults or add your own if you want to create different agents for different jobs.
10. When asked for a "Working Folder", set this to "W" (it is just a short name).

Depending on the OS you are installing the agent on:

• For Windows, you will be asked if you want to run this agent as a service. If you want it to automatically start when the Host powers up, then select Yes and click enter to select the default user to run the service as.
• If you are installing on a Mac, you have to run a separate command to install the service which is ./svc.sh install and then ./svc.sh start

Personally I have always installed agents as Services so I do not need to think about them, else you will need to run a separate command each and every time you need to start them (which some people do), just check the Azure docs for more details for your Operating system.

You now have a single agent setup, repeat steps 5 - 10 for additional agents with a different agent folder name.

All done except for the fish​

We are now at the end of our series, we have covered all the necessary bits to get your automation pipelines setup using the service(s) you require and you should be well armed for what lies ahead.

I have left personal notes through the articles to guide you in your journey, but here is a shortlist:

• Do not be afraid to use multiple services for different types of automation. I use Azure for Unity builds and publishing and I use GitHub for validation, tests and verification on all my code check ins.
• Use many agents for simple jobs, especially when they are quick, or even use hosted agents for those little things and take some weight off. It would be a VERY busy month to use all your free credits on simple jobs. But if you do exceed, then check and see if you want to move some or all of the work on to self-hosted agents, or mix and match.
• Use fewer agents for large jobs, should be fairly self explanatory as large jobs use a lot of power and will just slow each other down if run concurrently. Especially if you are running it on your dev PC. (might need more than one coffee while you wait).
• NEVER develop pipelines/jobs on your LIVE code branch, always make a FORK to a separate repo to experiment, or even use less code. It can sometimes take MANY runs of testing to get your pipeline working the ay you want it and you don't want/need to use your entire codebase while your testing. I always create a new fork/repo for testing and then copy over the YAML to my live repo when I'm happy.
• Experiment with your pipelines and also check what other projects do, if you see something you like that another project is doing, there is no harm looking at their pipelines and using it as a reference to build your own. The Microsoft Repos are especially for this.
• Did you know, you can also "generate your documentation" in a pipeline. Personally I have started using Docusaurus and Docfx to automate docs.

For GitHub if you want to use GitHub actions on PUBLIC repositories, then you need to edit the "Default runner group" and enable it (that caused me a week of head scratching as it is not well documented).

Hope this all helps and if you have questions, comment below!

Similar to GitHub Actions, Azure can automate the building / testing and deploying of your Unity solution. It is true, that Microsoft is on a journey to migrate all build automation to GitHub to offer a more accessible way for developers to automate their project, however,there are a few notable exceptions and capabilities that are still far superior in Azure Devops currently that are worth exploring, namely:

• Publish artifacts / builds per build.
• Finer control / articulation of your automation.
• The ability to manually run automation on command.
• Provide integration that can be consumed in GitHub Actions (useful for kicking off a pipeline when GitHub is finished)

On a personal note, I use a mix of GitHub Actions and Azure DevOps to utilise what each platform is best at. GitHub for quick tests / builds and validation, Azure for producing release / production builds and automating delivery to test suites/stores.

Its FREE​

Like GitHub Actions, the majority of Azure Pipelines is free to use and run, and a free Azure account to boot (with even some free Azure credits). The only time you start paying is for spinning up Build / Automation hosts to run your operations, there is a free tier but you can also offset this with your own Build Host (just like GitHub actions).

What can you automate?​

Automation provides a ton of capabilities to power and maintain your project, large or small, primarily with the focus on maintaining reliability and giving you an early warning of any potential problems that may be creeping into your project.

Automation can provide:

• Quick checks to ensure work is assigned correctly in your project.
• Validating information provided by the team or customers is accurate.
• Unit test validation. (if you are writing Unit tests, if you are not, why not?)
• Build testing for multiple platforms as required.
• Automated Version control, to ensure project/package versions are maintained. (you really do not want 500 copies of version 1.0 of your project do you?)
• Robust build automation, publishing and deployment.

The list goes on and in most cases, you are just organising what you want to test rather than writing lots of code to build your tests (in your workflow)

Azure Extensions​

Azure's library of extensions and features is well documented and has been in place for many years and there is an element if trustworthiness in the marketplace that GitHub simply cannot match. A lot of the extensions provide integrations into many of the features provided by Microsoft and its partners that enable things you may not have even considered (how about a cost calculator to tell you how much your operations could cost you?).

You can find the Azure DevOps Marketplace here - https://marketplace.visualstudio.com/azuredevops

There are extensions that provide things from:

• Dedicated Unity build automation - a set of reusable tools to fast-track your project automation.
• Integrations with Planning / optimisation tools such as Azure Boards and GitHub projects.
• Code management / validation / optimisation services to ensure your code is "mostly" error free.
• Test result exploring and navigation (although I haven't had this working with Unity Test outputs yet)

And soo much more.

The one thing to note is that "extensions" are enabled for your organisation and available to all pipelines, they are not on a per-project basis (so if there is a cost associated with an extension, there is only one charge, but most are free).

Install the Unity Tools for Azure DevOps extension​

For the purposes of this article (since it is about building Unity projects), install the awesome Unity Tools for Azure DevOps extension from the Azure marketplace and we will walk through it later.

https://www.unitydevops.com/

Automation images or Self-hosting​

The main (and likely only) cost for automation is the time and processing power needed to run your automation, in the majority of cases this is very minor and Azure Pipelines provide quite a substantial "free" level of processing time for running jobs (and fairly reasonable costs for extra).

Microsoft-hosted pipeline agents​

Depending on the requirements to run your actions, Microsoft provides several "images" on their platform to run your code for you:

You can find all the details on Microsoft's hosted images here - https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted

Essentially, these are cloud-hosted environments to run your automation.

For the astute observer who read the GitHub Actions article, you should note these are the same images that GitHub uses, fancy that 😱

Self Hosting​

The alternative is to "Self Host", simply meaning that instead of using a Microsoft-hosted server, you will be using your own box, be that a custom-built machine sitting in your cupboard or even your own workstation (having things run in the background seamlessly). You only need to make sure all the required software is installed (e.g. Unity, if you are doing Unity builds and NodeJS, if you are running NPM commands) and register your Host as a "Pipeline Agent". If you want, you can even setup multiple agents on the same machine for parallelising your workloads (just be careful how many you register so as not to overdo it on a single machine, especially if it is your developer workstation).

Microsoft's guide to setting up your own self-hosted agent - https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/v2-windows?view=azure-devops

Self-Hosting is by far the cheapest option as it is your own hardware running all the tasks and GitHub will not charge you a thing.

Setting up Self-hosted agents

Your first project​

Getting everything setup in Azure Pipelines is where you first encounter the required "management" setup for getting your automation up and running, on top of your GitHub source control, Azure treats your automation like a full-fledged project, providing many tools to manage and organise everything from:

• Tasks - Azure boards.
• Pipelines - Automation.
• Source Control - If not using GitHub.
• Test Plans - For managing Test runs and output.
• Artifacts - Published builds, data and dependencies

As you can see there is quite a lot available, but for this article, we are just going to focus on Pipelines, feel free to play with the others.

To begin, you need to Logon to Azure Devops and create a "Project" for your Product/automation, choosing if you want it public or private.

Create a new Project

With the project setup, it is time to click on the "Pipelines" tab on the left and get the automation flowing.

Your first pipeline​

Unlike GitHub, Azure pipelines does not hold your hand as much as GitHub does, although the syntax for building your automation is very similar.

However, as Azure Pipelines has been "around" a lot longer that GitHub actions, there are many more resources available to keep you going.

When you create your pipeline, you will be asked where the code (and essentially the automation configuration) is hosted, unlike GitHub, the code can be almost anywhere.

Assuming your code is on GitHub, select that option and then you will be asked to find your repo. By default, this shows you ALL the repositories your GitHub account has created or forked, to see all the repositories your account has access to (from other Organisations for example), then change the filter option (in the top-right) to "All Repositories, use the filter if you need to narrow down the search a bit.

You may get asked for permission to install the Azure pipeline extension for your project, this is just to enable Azure to use the GitHub API for your project/repository.

With the repository selected, all that is left is to initialise the pipeline with your workflow, if you don't have one already just select the "Starter Pipeline" and we will walk through it.

Changing your pipeline in Azure pipelines is exactly the same as GitHub actions, there is a workflow file checked in to your repository, and to update it you simply need to check in changes to that file, no need to return to Azure to update it if you do not want to (unless you like the graphical editor 😊)

Once you learn to read and build your own workflows, these are quite easy to follow, here is the Standard workflow using Dino's Unity Tools for Azure DevOps example yaml:

# Trigger the pipeline to run whenever a commit to the main branch is made.
trigger:
- main


# Use a custom agent pool called "Unity Windows" that manages custom agents

# that have the required Unity versions installed and any required SDKs for target platforms

# configured.
pool:
  name: Unity Windows

steps:

# Check out the code from the branch/pr we are building
- checkout: self


# (optional) Run the unit tests for the build
- task: UnityTestTask@1
  name: UnityUnitTests


# Build the Unity project to standalone. Since we are running on a Windows agent, this will produce

# an .exe executable and any dependency files needed.
- task: UnityBuildTask@3
  inputs:
    buildTarget: standalone
    outputPath: $(Build.BinariesDirectory)
    outputFileName: mygame


# Copy build output files to artifact staging directory.
- task: CopyFiles@2
  inputs:
    SourceFolder: $(Build.BinariesDirectory)
    Contents: '**'
    TargetFolder: $(Build.ArtifactStagingDirectory)
    CleanTargetFolder: true
    OverWrite: true


# Finally publish all items in artifact staging to the Azure Pipelines

# artifact storage. They will be available for sharing and/or further processing there.
- task: PublishBuildArtifacts@1
  inputs:
    PathtoPublish: $(Build.ArtifactStagingDirectory)
    ArtifactName: drop
    publishLocation: Container

The workflow is made up of several easy-to-understand sections:

1. Trigger​

The Trigger is an event that occurs in the Azure Pipeline, this can be overridden in the Pipeline Trigger configuration if you wish to make changes on the backend (also useful for making manual workflows run via command).

The most common trigger is the "Push" (when code is pushed to a branch) or "Pull_Request"" (when a PR is raised or updated from a push), however, if you check the list of things that can be "triggered" almost anything can be a trigger, from comments, to schedules and more.

The types of trigger can vary based upon where your source is held and what you are integrating with, from Azure Repos, GitHub, Bitbucket or even TFS (Team Foundation Server, the precursor to Azure Repositories/GitHub).

2. Agent Pool​

Unlike GitHub which identifies hosts to run the workflow on by attributes, Azure simply needs to identify the group of machines to run the Job on, organised in an "Agent Pool". You can see the Agent Pools you have configured by default from your Azure Organisation settings as shown below:

You can create your own or alternatively use one of the Microsoft-Hosted agents above by stating the "image name" you want to use, for example:

• windows-latest (latest version of windows)
• windows-2022 / windows-2019 (specify a specific version of windows)
• ubuntu-latest (latest linux ubuntu host)
• ubuntu-22.04 / ubuntu-20.04 / ubuntu-18.04 (specific versions of linux)
• macOS-latest(yes, you can even build on a Mac in Azure)
• macOS-12 / macOS-11 / macOS-10.15 (specific versions of MacOS)

Just remember that when you are using the Microsoft-Hosted agents, they are clean, any additional software you need (for example Unity) will need to be installed via the pipeline as it is running.

Personally, I always used a self-hosted agent, it has everything you need and only costs you what it costs to run it, no surprises (until it is down of course)

If you wish, you can also set the Agent Pool at the Job level instead of at the top of the pipeline, this enables you to run concurrent builds on multiple hosts, for example:

  jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: echo hello from Linux
- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - script: echo hello from macOS
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo hello from Windows

3. Jobs​

Jobs are simply a batch of work that will run on a single GitHub Runner (self-hosted or Github server). Each job is SELF-CONTAINED meaning that the work it carries out is isolated from any other work when it performs its tasks (steps). If two jobs are running on the same machine, they simply do not know about each other and cannot (by default) share work or information.

Jobs are optional (as shown in the example earlier), if you only have one set of steps then you can skip the Job setup.

You can have multiple jobs defined in a single workflow and even have dependencies (Job 1 runs, but Job 2 requires Job 1 to finish successfully to run) between jobs. There is a lot you can do but for the most part and in the majority of workflows I have developed, one job is usually enough.

In a Job, you define what it Runs-on (the host) and then a list of Steps (or tasks) to run in sequence. You can even make Conditional statements to state "IF"" a job should run, e.g. "Run this job IF the users name is X". (conditionals can also be applied to Steps, see later).

4. Steps​

Steps are exactly how they sound, like walking, you take one step and then the next (providing you have not fallen down in-between steps). Steps can also be given names and in most cases require parameters (With statements) in order to function, always check the documentation for a GitHub Action if you are unsure.

One thing to keep in mind is that By Default, ANY step that fails will prevent any further steps from being run as the pipeline fails on any exception. You can override this (especially if you are building for multiple platforms) if you want, or you can leave it at the default.

Based on Dino's yaml script above, the following steps are undertaken:

1. Checkout the latest code from the branch the workflow was triggered on (checkout: self)
2. Run any Unit tests located in the project (task: UnityTestTask@1), this is optional and can be skipped if you have no tests.
3. Build the Unity project for Windows Standalone (task: UnityBuildTask@3), obviously configurable to build for whichever platform you need.
4. When you package the build, we only want to include the actual build files and not everything (task: CopyFiles@2) so copy the actual project to a Staging Folder
5. Finally, we push the built project to the Azure Artifacts area (task: PublishBuildArtifacts@1) so you can download it from Azure.

Personally, I also include an Archive task (task: ArchiveFiles@2) in-between steps 4 & 5, so there is just one file to download 👍

Check out the other documentation on the Unity Tools for Azure DevOps site for more information regarding the extension.

Getting your Azure Pipelines running​

Once you have configured your Pipeline you can either Click "Save and Run" (the default) which will automatically run the pipeline straight away with whatever code you have checked in, or simply click "Save" which will commit your pipeline to your repository ready for the next time the trigger is fired.

Now every time you push to the branch you have configured (if using the example above) or if you set a PR as the trigger, each time a pull request is made, the pipeline will automatically run and spit out a build.

Just make sure that you have your Self Hosted agent setup correctly before running the pipeline, or ensure you have everything you need to run on a microsoft-hosted agent in the pipeline

I did find a YAML definition for Azure Pipelines to build Unity projects using a Microsoft-Hosts Windows Server agent that installs and runs unity here.

Too much more to mention​

There is soo much more that can be done with Azure Pipelines beyond the basics shown here, but you should now have a taste of what is in store, from the basics to the advanced.

Check the Azure Pipelines docs for more.

If you need to also check out the costs, have a look at the pricing page

Any questions, leave a comment below.

GitHub actions offers the power of Azure automation but in a far simpler and easy-to-use package, reducing the requirements and setup needed to get your automation off the ground. There are some things Azure still does better but for the most part, GitHub provides a wealthy estate of information and "out of the box" solutions for automating almost any workflow.

What can you automate?​

Automation provides a ton of capabilities to power and maintain your project, large or small, primarily with the focus on maintaining reliability and giving you an early warning of any potential problems that may be creeping into your project.

Automation can provide:

• Quick checks to ensure work is assigned correctly in your project.
• Validating information provided by the team or customers is accurate.
• Unit test validation (if you're writing Unit tests, if you are not, why not?)
• Build testing for multiple platforms as required
• Automated Version control, to ensure project/package versions are maintained (you really do not want 500 copies of version 1.0 of your project do you?)

The list goes on and in most cases, you are just organising what you want to test rather than writing lots of code to build your tests (in your workflow)

The GitHub Action Marketplace​

Azure Pipelines has a huge marketplace for pre-built workflows (things to do) to automate your work, GitHub too also has a growing marketplace, albeit a little harder to navigate, but nonetheless, still growing.

GitHub provides the basics right out of the door for you, everything from grabbing code, to setting up environments and GitHub pages.

You can find all the Official GitHub actions here - https://github.com/actions

GitHub also provides several starter workflows and guidance for constructing your flows.

Alongside the GitHub provided actions is a wealthy repository of community-written actions providing almost anything you need for your automation, including some that built up from GitHub's own Actions.

You can find the GitHub Actions marketplace here - https://github.com/marketplace?type=actions

Although, like with any other community driven content, care must be taken to ensure the action does what you need, but you will always have several to choose from. But rest assured, ALL THE SOURCE for each action is published, as it is a requirement for getting it listed on the marketplace.

Automation images or Self-hosting​

The main (and likely only) cost for automation is the time and processing power needed to run your automation, in the majority of cases this is very minor and GitHub provides quite a substantial "free" level of processing time for running actions (and fairly reasonable costs for extra).

GitHub hosting​

Depending on the requirements to run your actions, GitHub provides several "images" on their platform to run your code for you:

You can find all the details on GitHub's images here - https://github.com/actions/runner-images

Essentially, these are cloud-hosted environments to run your automation.

Self Hosting​

The alternative is to "Self Host", simply meaning that instead of using a GitHub server, you will be using your own box, be that a custom-built machine sitting in your cupboard or even your own workstation (having things run in the background seamlessly). You only need to make sure all the required software is installed (e.g. Unity if you are doing Unity builds and NodeJS if you are running NPM commands) and register your Host as a "GitHub Runner". If you want, you can even setup multiple runners on the same machine for parallelising your workloads (just be careful how many you register so as not to overdo it on a single machine, especially if it is your developer workstation).

Self-Hosting is by far the cheapest option as it is your own hardware running all the tasks and GitHub will not charge you a thing.

Setting up Self-hosted agents

Your first workflow​

The GitHub actions Starter Workflows repository gives you several "out of the box" solutions for workflows, including:

• ci: solutions for Continuous Integration workflows
• deployments: solutions for Deployment workflows
• automation: solutions for automating workflows
• code-scanning: solutions for Code Scanning
• pages: solutions for Pages workflows

Once you learn to read and build your own workflows, these are quite easy to follow, take the DotNet base workflow for example:

# This workflow will build a .NET project

# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net

name: .NET

on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 6.0.x
    - name: Restore dependencies
      run: dotnet restore
    - name: Build
      run: dotnet build --no-restore
    - name: Test
      run: dotnet test --no-build --verbosity normal

The workflow is made up of several easy-to-understand sections:

1. Name​

Each workflow needs a name, mainly so you can remember what it is for, but also it is what you see when the workflow is running in the Projects Actions tab for your repository.

2. Trigger​

The Trigger is an event that occurs in the GitHub API which each workflow will monitor and then run when the conditions are met.

The most common trigger is the "Push" (when code is pushed to a branch) or "Pull_Request"" (when a PR is raised or updated from a push), however, if you check the list of things that can be "triggered" almost anything can be a trigger, from comments, to new issues and more. Want a workflow that will email you when a new issue is created, or require customers to fill in certain fields when logging an issue, then workflows are there for you.

With most triggers, you also specify a "Condition" to determine the requirements when a trigger occurs, in the example above, the workflow will "run" when either a Pull Request or a Push is made to the "Default Branch" of your repository.

3. Jobs​

Jobs are simply a batch of work that will run on a single GitHub Runner (self-hosted or Github server). Each job is SELF-CONTAINED meaning that the work it carries out is isolated from any other work when it performs its tasks (steps). If two jobs are running on the same machine, they simply do not know about each other and cannot (by default) share work or information.

You can have multiple jobs defined in a single workflow and even have dependencies (Job 1 runs, but Job 2 requires Job 1 to finish successfully to run) between jobs. There is a lot you can do but for the most part and in the majority of workflows I have developed, one job is usually enough.

In a Job, you define what it Runs-on (the host) and then a list of Steps (or tasks) to run in sequence. You can even make "conditional statements" to state "IF"" a job should run, e.g. "Run this job IF the users name is X". (conditionals can also be applied to Steps, see later).

4. Steps​

Steps are exactly how they sound, like walking, you take one step and then the next (providing you have not fallen down in-between steps). Steps can also be given names and in most cases require parameters (With statements) in order to function, always check the documentation for a GitHub Action if you are unsure.

In the example above the Steps are:

1. Checkout the latest code from the branch the workflow was triggered on (actions/checkout@v3)
2. .NET is installed on the host, remembering that you need to validate the environment your action is running on to avoid it failing. This workflow needs the .NET runtime installed, so we check that it is installed and install it if is not (actions/setup-dotnet@v3), we also pass a parameter in the with clause to state which version we need (with: dotnet-version: 6.0.x)
3. We then run the DotNet command to restore any dependencies the project needs (as they are not usually in source) with the run command (run: dotnet restore) which executes in a terminal on the host.
4. With the project and all its dependencies ready, we run the DotNet build command to generate the project (dotnet build --no-restore)
5. Finally we run any testing code in our build to ensure everything is working as expected (dotnet test --no-build --verbosity normal) using the build we just generated.

One thing to keep in mind is that By Default ANY step that fails will prevent any further steps from being run as GitHub actions fails on any exception. You can override this (especially if you are building for multiple platforms) if you want, or you can leave it at the default.

Putting your GitHub workflow into Action​

(see what I did there :D )

Once you have created your workflow (or grabbed one from someone else), you simply need to get it "checked-in" to the repository you want it to run on, the primary requirement is that it MUST be available on the branch that it is targetting (in your trigger) or in the Default branch for anything that uses non-branch specific triggers (e.g. comments / issues).

If specify a trigger based on 'workflow_dispatch:', you can also run the workflow Manually from the GitHub Actions tab in your repository. Useful for testing.

on:
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

You just need to place the yml (Yaml script) file into the following directory structure for GitHub to recognise and pick up your workflow:

-> Root -> .github -> workflows

Once there and checked-in/committed, it will show up in your repositories Actions tab (provided you have enabled the Actions tab in your Project settings)

You will see the list of actions that have been detected by the GitHub API as well as a list of the previous runs and results for each workflow.

Too much more to mention​

There is soo much more that can be done with GitHub actions beyond the basics shown here, but you should now have a taste of what is in store, from the basics to the advanced.

Check the GitHub docs and learning portal for more.

If you need to also check out the costs, have a look at the pricing page where you will be nicely surprised just how much time you get for free.

Any questions, leave a comment below.