Working with Source Code (C# 7.3)
=================================

Accessing game data during runtime is possible by utilizing the generated source code.

This section provides examples using default class names, but it is possible to customize class names during the source code generation process. Additionally, this customization allows to avoid naming collisions with existing code.

Loading Game Data
-----------------

The following C# code creates ``GameData`` class and loads your game data into memory.

.. code-block:: csharp
  
  using System.IO;
  
  var fileStream = File.OpenRead("RpgGameData.gdjs"); // or .json
  var gameData = new GameData(fileStream, new Formatters.GameDataLoadOptions { 
    Format = Formatters.Format.Json,
    // Patches = new [] { patchStream1, patchStream2, ... }
  });
  fileStream.Dispose();

The file ``RpgGameData.gdjs`` could be :doc:`published <publication>` game data or original database file (.gdjs or .gdmp).  
  
Accessing Documents
-------------------

You can access your documents as a list:

.. code-block:: csharp

  var allHeroes = gameData.AllHeroes.AsList // -> IReadOnlyList<Hero>
  var heroes = gameData.Heroes.AsList // -> IReadOnlyList<Hero>

Or you can access specific documents by their ``Id`` or *Unique* properties:

.. code-block:: csharp

  var heroById = gameData.AllHeroes.Get(heroId); // -> Hero
  var heroByName = gameData.AllHeroes.ByName().Get(heroName); // -> Hero

``Settings`` schemas are accessed by name:

.. code-block:: csharp

  var startingHeroes = gameData.StartingSet.Heroes; // -> IReadOnlyList<Hero>
  
Formulas
--------

Formulas are executed with Invoke method:

.. code-block:: csharp

  var reward = gameData.LootSettings.RewardFormula.Invoke()  // -> int

Formula's parameters are passed as arguments of ``Invoke`` method.

Generated Code Extensions
-------------------------

When generating source code for game data, the resulting C# classes are declared as `partial <https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods>`_. This means that the classes can be extended by the programmer to add custom functionality.

For example, let's say that you have generated a ``GameData`` class for your game data. This class contains properties and methods for accessing and manipulating the data. However, you want to add some custom functionality to this class, such as a method for getting specific documents by criteria.

To do this, you can create a new C# file and declare a partial class with the same name as the generated ``GameData`` class. You can then define your custom method in this class, and it will be merged with the generated class at compile time.

Here is an example of how this could look:

.. code-block:: csharp
  // should be in same namespace as generated GameData class
  public partial class GameData {
  
      public IEnumerable<Hero> GetReligiousHeroes() {
          return this.AllHeroes.AsList.Where(hero => hero.Religious);
      }
  
  }

In this example, the ``GameData`` class is declared as partial, and two partial classes are defined with the same name: one generated by the source code generation process and one containing custom code added by the programmer.

By using partial classes in this way, you can extend the functionality of the generated classes without modifying the generated code directly. This allows you to keep your custom code separate from the generated code, making it easier to maintain and update your game data classes over time.

There is also two extension points on ``GameData`` class:

.. code-block:: csharp

  partial void OnInitialize(); // Called after loading and prepping all data.

See also
--------

- :doc:`Generating Source Code <generating_source_code>`
- :doc:`GENERATE CSHARPCODE Command <../advanced/commands/generate_csharp_code>`