docs: adding initial documentation
This commit is contained in:
parent
eca05f8970
commit
32be8aad6e
95
docs/gallium/index.md
Normal file
95
docs/gallium/index.md
Normal file
|
@ -0,0 +1,95 @@
|
|||
# MfGames' Gallium
|
||||
|
||||
Gallium is a simple [Entity-Component-System](https://en.wikipedia.org/wiki/Entity_component_system) (ECS) written to mimic much of the `System.Linq` namespace in C#. It is focused on less on performance and volume, and more with following established C# patterns to make it easy to use.
|
||||
|
||||
## Installation
|
||||
|
||||
At the moment, Gallium is not in nuget.org. Instead, it can be downloaded from the MfGames repository by configuring `NuGet.config` to pull the `MfGames.*` packages from [src.mfgames.com](https://src.mfgames.com/):
|
||||
|
||||
```xml
|
||||
<!-- NuGet.config -->
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<configuration>
|
||||
<packageSources>
|
||||
<clear />
|
||||
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
|
||||
<add key="mfgames.com" value="https://src.mfgames.com/api/packages/mfgames-cil/nuget/index.json" protocolVersion="3" />
|
||||
</packageSources>
|
||||
<packageSourceMapping>
|
||||
<packageSource key="nuget.org">
|
||||
<package pattern="*" />
|
||||
</packageSource>
|
||||
<packageSource key="mfgames.com">
|
||||
<package pattern="MfGames.*" />
|
||||
</packageSource>
|
||||
</packageSourceMapping>
|
||||
</configuration>
|
||||
>
|
||||
```
|
||||
|
||||
There is only one package, `MfGames.Gallium` which can be installed from inside Rider, Visual Studio, or via the `dotnet` command line:
|
||||
|
||||
```shell
|
||||
dotnet add package MfGames.Gallium
|
||||
```
|
||||
|
||||
## Namespace
|
||||
|
||||
The bulk of the library is located in the `MfGames.Gallium` namespace.
|
||||
|
||||
```csharp
|
||||
using MfGames.Gallium;
|
||||
```
|
||||
|
||||
## Entities
|
||||
|
||||
The primary object of the ECS is the `Entity` class, a flyweight class with little more than an integer identifier and a collection of components.
|
||||
|
||||
```csharp
|
||||
// To create an entity with a specific identifier.
|
||||
Entity entity1 = new(13);
|
||||
|
||||
Assert.Equal(13, entity.Id);
|
||||
|
||||
// To create an entity with an automatically incrementing identifier starting
|
||||
// with zero.
|
||||
Entity entity2 = new();
|
||||
|
||||
// To create a copy of the entity with a new identifiers but a shallow copy
|
||||
// of the components inside the entity.
|
||||
Entity entity3 = entity2.Copy();
|
||||
|
||||
Assert.NotEqual(entity2.Id, entity3.Id);
|
||||
|
||||
// To create a duplicate copy of the entity, including components, and with
|
||||
// the same identifier.
|
||||
Entity entity4 = entity2.ExactCopy();
|
||||
|
||||
Assert.Equal(entity2.Id, entity4.Id);
|
||||
```
|
||||
|
||||
> 📝 Note: The use of `int` for `Entity.Id` which based on the intended usage of the library where there will rarely be more than two billion files and objects loaded into memory. However, we have had sites that exceeded the 32k file limit, so the `int` was considered "good enough" for our purposes.
|
||||
|
||||
## Components
|
||||
|
||||
A component in Gallium is defined by its `Type` (as in `value.GetType()`) and generics. This cannot be changed in any method, but the class that the component is registered underneath can be a parent class.
|
||||
|
||||
```csharp
|
||||
entity.Add("value");
|
||||
|
||||
Assert.Equal("value", entity.Get<string>());
|
||||
Assert.True(entity.Has<string>());
|
||||
Assert.ThrowsException(() => entity.Add("second value"));
|
||||
|
||||
entity.Remove<string>();
|
||||
|
||||
Assert.False(entity.Has<string>());
|
||||
Assert.ThrowsException(() => entity.Get(typeof(string)));
|
||||
|
||||
entity.Add("value2");
|
||||
entity.Set("value3");
|
||||
|
||||
Assert.Equal("value3", entity.Get<string>());
|
||||
|
||||
entity.Add<object>("value4");
|
||||
```
|
6
docs/index.md
Normal file
6
docs/index.md
Normal file
|
@ -0,0 +1,6 @@
|
|||
# MfGames' CIL Libraries for C# and DotNet
|
||||
|
||||
## Libraries
|
||||
|
||||
- [Gallium](./gallium/)
|
||||
- [Nitride](./nitride/)
|
0
docs/nitride/index.md
Normal file
0
docs/nitride/index.md
Normal file
Loading…
Reference in a new issue