Nexus Mods App

https://nexus-mods.github.io/NexusMods.App/
Admin
Nexus Mods App is a mod manager for PC games that enables users to download, install, and manage...
Tokens:97,449
Snippets:538
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### C# Mod Installer Example (SifuModInstaller)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/InstallingMods

This C# code provides an example of a `IModInstaller` implementation for the Unreal Engine 4 game, Sifu. It demonstrates how to locate and extract `.pak` files, placing them in the `Content/Paks/~mods` folder.

```C#
public class SifuModInstaller : AModInstaller
{
    private static readonly Extension PakExt = new(".pak");
    private static readonly RelativePath ModsPath = "Content/Paks/~mods".ToRelativePath();

    public SifuModInstaller(IServiceProvider serviceProvider) : base(serviceProvider) { }

    public override async ValueTask<IEnumerable<ModInstallerResult>> GetModsAsync(
        ModInstallerInfo info, 
        CancellationToken cancellationToken = default) 
    {
        // Find a PAK file
        var pakFile = info.ArchiveFiles.GetFiles()
            .FirstOrDefault(node => node.Path().Extension == PakExt);

        if (pakFile == null)
            return NoResults;

        // Get folder for PAK file.
        var pakPath = pakFile.Parent();
        var modFiles = pakPath!.GetFiles()
            .Select(kv => kv.ToStoredFile(
                new GamePath(LocationId.Game, ModsPath.Join(kv.Path().RelativeTo(pakPath!.Path()))) 
            ));

        return new [] { new ModInstallerResult
        {
            Id = info.BaseModId,
            Files = modFiles,
            Name = pakPath!.FileName()
        }}
    }
}
```

--------------------------------

### C# AGame Derivative Example (Sifu)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/InstallingMods

This C# code demonstrates how to integrate the custom `SifuModInstaller` into an `AGame` derivative class (`Sifu`). It shows how to register the installer within the `MakeInstallers` method, ensuring the app utilizes it during the mod installation process.

```C#
// 👇 in your AGame Derivative
public class Sifu : AGame, ISteamGame, IEpicGame
{
    // Right here! 🫰
    protected override IEnumerable<IModInstaller> MakeInstallers(IServiceProvider provider) => new[]
    {
        new SifuModInstaller(provider)
    };
}
```

--------------------------------

### Install MkDocs Material and Plugins

Source: https://nexus-mods.github.io/NexusMods.App/Nexus/Pages/contributing

Install MkDocs Material and the redirects plugin using pip to enable documentation site generation. Depends on Python 3 being installed; inputs pip commands, outputs installation confirmation or errors. Restart command prompt on Windows for changes to take effect; use virtual environment on Linux to avoid system conflicts.

```bash
# Restart your command prompt before running this command.
pip install mkdocs-material
pip install mkdocs-redirects
```

--------------------------------

### Serve MkDocs Site Locally

Source: https://nexus-mods.github.io/NexusMods.App/Nexus/Pages/contributing

Navigate to the project directory and start a local development server for MkDocs to preview the site. Depends on MkDocs installation and a valid mkdocs.yml file; inputs directory path and serve command, outputs a local URL for browser access. Automatically reloads on file changes; limited to local machine access, not public.

```bash
# Move to project folder.
cd <Replace this with full path to folder containing `mkdocs.yml`>
mkdocs serve
```

--------------------------------

### Bannerlord SubModule.xml Example

Source: https://nexus-mods.github.io/NexusMods.App/developers/games/0004-MountAndBlade2Bannerlord

Provides a comprehensive example of a SubModule.xml file, which acts as the metadata descriptor for a Bannerlord mod. It includes essential information such as module name, ID, version, dependencies, and custom configurations for loading additional game assets or logic.

```xml
<Module>
  <Name value="Player Settlement"/>
  <Id value="PlayerSettlement"/>
  <Version value="v6.0.2"/>
  <Url value="https://www.nexusmods.com/mountandblade2bannerlord/mods/7298" />
  <SingleplayerModule value="true"/>
  <MultiplayerModule value="false"/>
  <Official value="false"/>
  <DefaultModule value="false" />
  <ModuleCategory value="Singleplayer" />
  <ModuleType value="Community" />
  <UpdateInfo value="NexusMods:7298" />
  <!-- Used by PlayerSettlement to dynamically add more settlement variants -->
  <PlayerSettlementsTemplates path="ModuleData/Player_Settlement_Templates" />
  <!-- Used by PlayerSettlement to dynamically blacklist settlement variants -->
  <PlayerSettlementsTemplatesBlacklist path="ModuleData/template_blacklist.txt" />
  <DependedModules>
    <DependedModule Id="Bannerlord.Harmony" />
    <DependedModule Id="Bannerlord.ButterLib" />
    <DependedModule Id="Bannerlord.UIExtenderEx" />
    <DependedModule Id="Bannerlord.MBOptionScreen" />
    <DependedModule Id="Native"/>
    <DependedModule Id="SandBoxCore"/>
    <DependedModule Id="Sandbox"/>
    <DependedModule Id="StoryMode" />
  </DependedModules>
  <!-- Community Metadata -->
  <DependedModuleMetadatas>
    <DependedModuleMetadata id="Bannerlord.Harmony" order="LoadBeforeThis" version="v2.2.2" />
    <DependedModuleMetadata id="Bannerlord.ButterLib" order="LoadBeforeThis" version="v2.8.15" />
    <DependedModuleMetadata id="Bannerlord.UIExtenderEx" order="LoadBeforeThis" version="v2.12.0" />
    <DependedModuleMetadata id="Bannerlord.MBOptionScreen" order="LoadBeforeThis" version="v5.10.1" />
    <DependedModuleMetadata id="Native" order="LoadBeforeThis" version="1.0.0.*" />
    <DependedModuleMetadata id="SandBoxCore" order="LoadBeforeThis" version="1.0.0.*" />
    <DependedModuleMetadata id="Sandbox" order="LoadBeforeThis" version="1.0.0.*" />
    <DependedModuleMetadata id="StoryMode" order="LoadBeforeThis" version="1.0.0.*" />
    <DependedModuleMetadata id="CustomBattle" order="LoadBeforeThis" version="1.0.0.*" optional="true" />
  </DependedModuleMetadatas>
  <SubModules>
    <SubModule>
      <Name value="PlayerSettlement"/>
      <DLLName value="PlayerSettlement.dll"/>
      <SubModuleClassType value="BannerlordPlayerSettlement.Main"/>
      <Tags />
    </SubModule>
  </SubModules>
  <Xmls/>
</Module>

```

--------------------------------

### Install Python 3 using shell commands

Source: https://nexus-mods.github.io/NexusMods.App/Nexus/Pages/contributing

Install Python 3 on Windows using winget or on Arch Linux using pacman. This step is essential for running MkDocs and requires administrative privileges or package manager access. Outputs successful installation or error messages; limited to supported package managers.

```bash
winget install Python.Python.3
```

```bash
pacman -S python-pip # you should already have Python
```

--------------------------------

### Create and Activate Virtual Environment on Linux

Source: https://nexus-mods.github.io/NexusMods.App/Nexus/Pages/contributing

Set up a Python virtual environment on Linux to isolate MkDocs installation from system Python. Requires Python and virtualenv module; inputs venv creation and activation commands, outputs environment activation prompt. Prevents system modifications; must be activated before running pip installs or MkDocs commands.

```bash
python -m venv mkdocs # Create the environment
source ~/mkdocs/bin/activate # Enter the environment

pip install mkdocs-material
pip install mkdocs-redirects
```

--------------------------------

### C# Interface: IModInstallDestination

Source: https://nexus-mods.github.io/NexusMods.App/developers/decisions/backend/0010-basic-advanced-installer-suggestions

Defines the interface for representing a target used for suggestions for installing mods within the Advanced Installer. It includes properties for destination game path, valid file extensions and file extensions to discard.

```C#
/// <summary>
/// Represents a target used for suggestions for installing mods within the Advanced Installer.
/// </summary>
public interface IModInstallDestination
{
    /// <summary>
    /// GamePath to which the relative mod file paths should appended to.
    /// </summary>
    public GamePath DestinationGamePath { get; init; }

    /// <summary>
    /// List of known recognizable file extensions for direct children of the target <see cref="DestinationGamePath"/>.
    /// NOTE: Only include file extensions that are only likely to appear at this level of the folder hierarchy.
    /// </summary>
    public IEnumerable<Extension> KnownValidFileExtensions { get; init; }

    /// <summary>
    /// List of file extensions to discard when installing to this target.
    /// </summary>
    public IEnumerable<Extension> FileExtensionsToDiscard { get; init; }
}
```

--------------------------------

### Bannerlord Module Structure Example

Source: https://nexus-mods.github.io/NexusMods.App/developers/games/0004-MountAndBlade2Bannerlord

Illustrates the typical directory structure for a Bannerlord module, emphasizing the critical SubModule.xml file for metadata and configuration. Other folders like AssetPackages, Atmospheres, GUI, ModuleData, and SceneObj are optional and depend on the mod's functionality.

```tree
MyModule
├── AssetPackages
│   └── assetpackage.tpac
├── Atmospheres
│   ├── Interpolated
│   │   └── interpolatedatmosphere.xml
│   └── atmosphere.xml
├── bin
│   └── Win64_Shipping_Client
│       └── MyModule.dll
├── GUI
│   ├── Brushes
│   └── Prefabs
├── ModuleData
├── SceneObj
└── SubModule.xml

```

--------------------------------

### Avalonia Style Example

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UIStylingGuidelines

Demonstrates a basic Avalonia style applying font size and weight to a TextBlock with a class 'H1'. This style uses Avalonia UI style selector syntax.

```XAML
<Style Selector="TextBlock.H1">
    <Setter Property="FontSize" Value="24"/>
    <Setter Property="FontWeight" Value="Bold"/>
</Style>
```

--------------------------------

### App Configuration for Locale Override (JSON)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/LocalizationAndTranslation

Demonstrates how to set a locale override in the AppConfig.json file to force the application to start with a specific language. This setting is applied during the application's startup phase.

```json
"LauncherSettings": {
  "LocaleOverride": ""
}
```

--------------------------------

### Avalonia Style Include from Assembly

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UIStylingGuidelines

Demonstrates how to include styles from another assembly or NuGet package using the 'avares://' prefix.

```XAML
<Application... >
    <Application.Styles>
        <FluentTheme/>
        <StyleInclude Source="avares://MyApp.Shared/Styles/CommonAppStyles.axaml"/>
    </Application.Styles>
</Application>
```

--------------------------------

### Referencing Localized Text in C#

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/LocalizationAndTranslation

Shows how to access localized strings directly from C# code using a static `Language` class. It also includes an example of using `string.Format` for localized strings that require parameter injection.

```csharp
var text = Language.MyGames
```

```csharp
// Language.Hello is "Hello {0}"
string.Format(Language.Hello, user)
```

--------------------------------

### Avalonia Style Preview Example

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UIStylingGuidelines

This XAML snippet shows how to define a preview for Avalonia Styles, allowing developers to visualize different style variations within the design tools. It uses a WrapPanel to arrange Border elements with different classes, demonstrating 'Rounded', 'OutlineStrong', and 'OutlineModerate'.

```xaml
<Design.PreviewWith>
        <WrapPanel Margin="10" Width="600">
            <Border Classes="Rounded OutlineStrong" Padding="16">
                <TextBlock Text="OUTLINE Strong" />
            </Border>
            <Border Classes="Rounded OutlineModerate" Padding="16">
                <TextBlock Text="OUTLINE Moderate" />
            </Border>
        </WrapPanel>
</Design.PreviewWith>
```

--------------------------------

### View Constructor and Control Initialization - C#

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Basic View constructor that initializes the component and demonstrates the auto-generated control reference mechanism. Shows how partial classes work with Avalonia's source generation to provide strongly-typed access to named XAML controls.

```csharp
public MyView()
{
    InitializeComponent();
}

```

```csharp
// <auto-generated />
partial class MyView
{
    internal global::Avalonia.Controls.TextBlock MyTextBlock;

    public void InitializeComponent(bool loadXaml = true)
    {
        if (loadXaml)
        {
            AvaloniaXamlLoader.Load(this);
        }

        MyTextBlock = this.FindNameScope()?.Find<global::Avalonia.Controls.TextBlock>("MyTextBlock");
    }
}

```

--------------------------------

### Install .NET Framework in WINEPREFIX

Source: https://nexus-mods.github.io/NexusMods.App/developers/decisions/backend/0018-running-tools-on-linux

Installs .NET Framework 4.8 runtime in a specified WINEPREFIX using winetricks. This is necessary for running Windows applications that depend on .NET Framework. Can be adapted for other .NET versions like dotnet6 or dotnet7.

```bash
WINEPREFIX=/home/sewer/.steam/steam/steamapps/compatdata/213610/pfx winetricks dotnet48
```

--------------------------------

### Immutable Data Model Example

Source: https://nexus-mods.github.io/NexusMods.App/developers/concepts/0000-immutable-modlists

This example demonstrates a structured way to represent modlist data, including mods, files, and provenance information like archive name, hash, and path. This structure facilitates on-demand file extraction and efficient version management.

```yaml
Mod1:
    foo.dds:
      Hash: 0x443434
      DataProvinance:
        ArchiveName: my_mod.7z
        ArchiveHash: 0x4424233
        ArchivePath: path/to/foo.dds
Mod2:
    bar.dds:
      - ...
    baz.dds:
      - ...

```

--------------------------------

### Avalonia View Code Behind Initialization

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Demonstrates the basic structure of an Avalonia view's code-behind file, including the constructor and the InitializeComponent() call. This is the foundation for creating user interfaces in Avalonia.

```csharp
public partial class MyView : UserControl
{
    public MyView()
    {
        InitializeComponent();
    }
}
```

--------------------------------

### Configure Game Locations with GetLocations

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/AddingAGame

Override the GetLocations method to specify where the app should look for game files. This example adds both the game folder and AppData directory.

```csharp
protected override IReadOnlyDictionary<LocationId, AbsolutePath> GetLocations(IFileSystem fileSystem, GameLocatorResult installation)
{
    return new Dictionary<LocationId, AbsolutePath>
    {
        { LocationId.Game, installation.Path },
        { LocationId.AppData, fileSystem.GetKnownPath(KnownPath.LocalApplicationDataDirectory).Combine("Skyrim") }
    };
}
```

--------------------------------

### Avalonia Style Import from XAML File

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UIStylingGuidelines

Shows how to define styles in a separate XAML file and import them into the Application. This promotes code reusability and organization.

```XAML
<Styles xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style Selector="TextBlock.h1">
        <Setter Property="FontSize" Value="24"/>
        <Setter Property="FontWeight" Value="Bold"/>
    </Style>
</Styles>
```

```XAML
<Application... >
    <Application.Styles>
        <FluentTheme/>
        <StyleInclude Source="/TextBlockStyles.axaml"/>
    </Application.Styles>
</Application>
```

--------------------------------

### Implement Steam Game ID Interface

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/AddingAGame

Example of implementing the ISteamGame interface by providing the Steam App ID. The ID can be found in SteamDB or appmanifest files.

```csharp
public IEnumerable<uint> SteamIds => new[] { 252950u };
```

--------------------------------

### Registering Views for ViewModels in App Startup

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Registers all Views implementing IViewFor<TViewModel> in the current assembly to their corresponding ViewModels for automatic View resolution in ReactiveUI.

```csharp
public partial class App
{
    public App()
    {
        Locator.CurrentMutable.RegisterViewsForViewModels(Assembly.GetCallingAssembly());
    }
}
```

--------------------------------

### DI Service Registration Examples (C#)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/DependencyInjection

Provides three common patterns for registering services with the DI container: registering a type as itself, registering a type as an interface, and registering a type as both.

```csharp
// 1. Register 'Foo' as 'Foo'
services.AddSingleton<Foo>();

```

```csharp
// 2. Register 'Foo' as 'IFoo'
services.AddSingleton<IFoo, Foo>();

```

```csharp
// 3. Register Foo as 'IFoo' and 'Foo'
services.AddAllSingleton<IFoo, Foo>();

```

--------------------------------

### ViewModel Property Initialization (C#)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Initializes a public string property 'Greeting' in the MyViewModel class with a default value of 'Hello World!'. This property is get-only initially.

```csharp
public class MyViewModel
{
    //                updated here 👇
    public string Greeting { get; set; } = "Hello World!";
}

```

--------------------------------

### Basic UI StackPanel (XAML)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Defines a simple XAML StackPanel containing a TextBlock named 'MyTextBlock' and a Button named 'MyButton'. This serves as the UI structure for the example.

```xaml
<StackPanel>
    <TextBlock x:Name="MyTextBlock" />
    <Button x:Name="MyButton">Click Me!</Button>
</StackPanel>

```

--------------------------------

### Avalonia Style Application

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UIStylingGuidelines

Shows how to apply the style to a TextBlock using the Classes attribute. The selector links the style to a control.

```XAML
<Window>
    <StackPanel Margin="20">
        <TextBlock Classes="H1" Text="Heading 1"/>
    </StackPanel>
</Window>
```

--------------------------------

### Unit Testing with AutoFileSystem (C#)

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UsingIFileSystem

Shows how to write unit tests for services using IFileSystem. It utilizes the AutoFileSystem attribute from NexusMods.Paths.TestingHelpers and InMemoryFileSystem for mock file system operations during testing.

```csharp
using NexusMods.Paths.TestingHelpers;
using Xunit;

public class MyServiceTests
{
    [Theory, AutoFileSystem]
    public async Task Test_GetCharCount(InMemoryFileSystem fs, AbsolutePath textFile, string contents)
    {
        fs.AddFile(textFile, contents);

        var service = new MyService(fs);

        var result = await service.GetCharCount(textFile);
        result.Should.Be(contents.Length);
    }
}
```

--------------------------------

### Create ViewModel with Observable Property

Source: https://nexus-mods.github.io/NexusMods.App/developers/development-guidelines/UICodingGuidelines

Defines a simple ViewModel with an observable property using ReactiveUI pattern. The Greeting property demonstrates basic property initialization using C# expression-bodied properties. This snippet serves as the foundation for MVVM architecture in Avalonia applications.

```csharp
public class MyViewModel
{
    public string Greeting { get; } = "Hello World!";
}
```
Tokens:
Raw