DOCSEARCHbyAlgolia
Submit Docs

Nitrox Documentation

website·Indexed 29 days ago

https://subnauticanitrox.github.io/Documentation/

Documentation for Nitrox, an open-source multiplayer modification for Subnautica. Includes development guides on repository setup, method patching, debugging with dnSpyEx, and contributing guidelines for the dev team.

Tokens
4.3K
Snippets
19
Records
34
Agent score
75%

What's inside Nitrox

  1. Understand the Nitrox Server and Launcher architecture

    The Nitrox ecosystem consists of two primary application projects:

    • Nitrox.Server.Subnautica: The server application responsible for managing game entities and serialization logic to communicate with clients.
    • Nitrox.Launcher: An Avalonia-based application used to start the server and/or the Subnautica game. It performs a critical step of patching the Assembly-CSharp.dll of Subnautica to inject the Nitrox client code before the game launches.

  2. Nitrox Library Project Reference

    The Nitrox architecture relies on several library projects to handle shared logic, patching, and client-side functionality:

    • Nitrox.Model: Contains shared code (e.g., Packet classes) used by both client and server that does not directly reference Subnautica code.
    • Nitrox.Model.Subnautica: Contains shared code that includes serialization logic specifically for Subnautica game entities.
    • NitroxPatcher: A library injected into Subnautica using the HarmonyX library. It handles bootstrapping the client and modifying internal data structures.
    • NitroxClient: Injected via NitroxPatcher; contains the UDP client, packet handlers, and MonoBehaviours.
    • NitroxUnity: An asset library providing UI and game components introduced by Nitrox.
    • Nitrox.Test: The core unit testing project for the entire ecosystem.

  3. Access Subnautica Nitrox project tracking and status

    Project status, milestones, and task tracking for Subnautica Nitrox are maintained across the following platforms:

    • Main project overview: GitHub repository
    • Development milestones: GitHub Milestones
    • Task management: Trello
    GitHub: https://github.com/SubnauticaNitrox/Nitrox
Milestones: https://github.com/SubnauticaNitrox/Nitrox/milestones?sort=completeness&direction=desc
Trello: https://trello.com/b/lNa9jUWc/subnautica-nitrox

  4. Understand Subnautica Nitrox core terminology

    The following terms are used throughout the documentation to describe the system's architecture:

    • World data: Refers to data associated with game entities such as creatures, vehicles, and bases.
    • Signal: Refers to a C#/.NET event or callback mechanism used for communication within the mod.

  5. Install optional tools for Nitrox development

    Depending on your workflow, the following optional tools are recommended for contributing to Nitrox:

    • Code Analysis & Debugging: dnSpy or dnSpyEx (for decompiling and live debugging Subnautica code), and SonarLint or ReSharper (for code quality improvement in Visual Studio).
    • Asset Management: UABEA (Unity Assets Bundle Extractor) for viewing Unity game assets.
    • Version Control: SourceTree (GUI for Git), though the git CLI is highly recommended.
    • Development Frameworks: Additional Microsoft .NET SDKs and .NET targeting packs.
    • Game Engine: Unity 2019.4.36f1 is required if you intend to work on the visual aspects of the mod or game.

  6. Set up a local development environment for Nitrox

    To contribute to Nitrox, you must fork the repository to your own GitHub account and clone it locally. It is highly recommended to add the official Nitrox repository as an upstream remote to keep your local copy synchronized with the main project.
    # Clone your fork
git clone https://github.com/<your-github-name>/Nitrox.git

# Add the main Nitrox repository as upstream
git remote add upstream https://github.com/SubnauticaNitrox/Nitrox.git

  8. Follow Subnautica Nitrox basic code design principles

    Adhere to the following design principles when contributing code:

    • Defensive Programming: Use Validate.NotNull, Try* APIs, and logging when retrieving game data to identify issues early.
    • Easy to Remove Code: Ensure types can be removed trivially. Use interfaces or split types to reduce dependencies.
    • Inversion of Control (IoC): Supply stateful APIs as constructor parameters. Dependency Injection (DI) is recommended but not required.
    • Small Interfaces: Keep interfaces small and focused. Prefer implementing multiple small interfaces over one large one.
    • Consistent Naming: Use verbs for normal functions (except callbacks). Avoid past tense unless the function is an event.
    • Avoid Deep Inheritance: Avoid using more than two parent classes; prefer composition, functional, or procedural programming.
    • Avoid Code Duplication: Refactor code that is duplicated in three or more places, provided the sections have the same goal.

  9. Inspect game and Nitrox code in dnSpy

    To view and set breakpoints in the game's source code while debugging:

    1. Open the Modules window via Debug > Windows > Modules.
    2. Double-click Assembly-CSharp.dll to view the game's code.
    3. To debug Nitrox specifically, locate the Nitrox modules in the same list after the patcher has loaded them.

    Breakpoints can be placed in any module; the game will pause and display local variables when a breakpoint is hit.

  11. Prepare and file a Pull Request (PR)

    Before filing a PR, ensure the code compiles, runs without errors, and merges without conflicts. To avoid structural breakages (such as renamings or refactors) that GitHub's conflict checker might miss, merge the master branch into your branch or rebase your branch on top of master before submitting.

    Do not remove existing code simply because it is non-functional or causes exceptions. Instead, attempt to fix the issue in a separate PR or notify the development team via a GitHub issue.

  12. Apply to join the Subnautica Nitrox development team

    Subnautica Nitrox is an open-source multiplayer modification for Subnautica. To join the development team, candidates should have experience with C#, Object-Oriented Programming (OOP), the Unity Engine component system, and Git version control. To apply, request to join in one of the public channels on the project's Discord server.