Trident Net

Trident.Net

Declarative Minecraft instance tooling: core libraries, modpack pipelines, and a command-line product.

简体中文 · Library · CLI · Repository Layout · AI Disclosure

Trident.Net is the .NET implementation of Trident: a set of core libraries for Minecraft instances, modpacks, package repositories, and accounts, plus the trident command-line tool built on the same core capabilities.

Trident keeps an instance declarative, rebuildable, importable, exportable, and friendly to automation. The libraries define the model and execution engine; the CLI exposes those capabilities as a product-ready entry point for local play, modpack maintenance, and CI/CD publishing.

One Model, Two Entrypoints

The core object in Trident is profile.json. It describes the game version, loader, packages, rules, and runtime overrides. During deployment, Core resolves the profile into a launchable .minecraft directory. The CLI provides commands for creating, importing, building, running, exporting, and managing packages.

TridentCore.Abstractions  -> file models, repository interfaces, trackers, account interfaces
TridentCore.Core          -> instance management, deploy/run engine, import/export, remote repositories, auth services
TridentCore.Pref          -> Trident package URL parsing and formatting
TridentCore.Cli           -> end-user trident command
  ├── Operations/         -> shared business logic (used by both Commands and Tools)
  ├── Commands/           -> Spectre.Console.Cli command entry points + rich output formatting
  ├── Tools/              -> MCP tool entry points + JSON serialization

Trident As A Library

This section is for developers embedding Trident into launchers, desktop apps, server tools, or automation systems.

Data Layout

Trident only manages data under the selected home directory. By default, home is resolved by walking up from the current directory and looking for .trident; if none is found, Trident falls back to ~/.trident. Host applications can override PathDef.Default or PathDef.HomeLocatorDefault before first use.

.trident/
├── cache/
│   ├── assets/              # Minecraft assets indexes/objects
│   ├── libraries/           # Minecraft libraries
│   ├── packages/            # repository package files and metadata
│   └── runtimes/            # Java runtimes
├── instances/
│   └── {key}/
│       ├── profile.json     # declarative instance metadata
│       ├── data.lock.json   # deployment lock data
│       ├── data.pack.json   # pack data
│       ├── build/           # projected .minecraft output; also holds runtime mutations to imported content
│       ├── import/          # imported layer, usually from modpacks or exportable files
│       └── persist/         # user-persistent data such as saves, screenshots, options.txt
└── .trident.cli/
    ├── accounts.json        # CLI-private account configuration
    ├── repositories.json    # CLI-private repository configuration
    └── settings.json        # CLI-global launch defaults and other config

Core Concepts

• Profile: the declarative instance entrypoint, including name, Minecraft version, loader, package Prefs, rules, and

runtime overrides.

• Deploy: combines the profile, remote metadata, cached files, and local layers into build/, then writes

data.lock.json.

• Layer: import/ stores modpack or exportable files (projected as real files into build/ so the game reads them

directly), and persist/ stores user data (symlinked into build/). Runtime mutations to imported content land in build/.

• Projection: deployment incrementally projects the virtual file structure into build/ — import as real files,

packages and persistence as symlinks.

• Repository: a unified interface for package sources such as Modrinth and CurseForge; package identities use Trident

Prefs.

• Tracker: deploy, install, update, and run operations expose state, stage, and progress through trackers for UI and CLI

subscribers.

Capabilities

• Create, scan, update, and delete managed instances.
• Deploy vanilla Minecraft, loaders, runtimes, dependencies, and build artifacts.
• Run instances with offline accounts, Microsoft accounts, memory/window options, Java home, and quick-connect settings.
• Import and export trident, modrinth, and curseforge modpack formats.
• Query packages, versions, dependencies, and reverse dependencies inside an instance.
• Resolve Forge, NeoForge, Fabric, and Quilt loaders through PrismLauncher metadata.

Integration

Core is primarily integrated through dependency injection. src/TridentCore.Cli/Startup.cs is the most complete host example and shows how to register HTTP clients, caches, importers, exporters, remote services, and core managers.

services.AddMemoryCache();
services.AddDistributedMemoryCache();

services
    .AddTransient()
    .AddTransient()
    .AddTransient()
    .AddTransient()
    .AddTransient()
    .AddTransient()
    .AddLifetimeRuntime()
    .AddPrismLauncher()
    .AddMojangLauncher()
    .AddMicrosoft()
    .AddXboxLive()
    .AddMinecraft()
    .AddMclogs()
    .AddSingleton()
    .AddSingleton()
    .AddSingleton()
    .AddSingleton()
    .AddSingleton();

In your own application, prefer these managers over direct file manipulation: ProfileManager manages the profile lifecycle, InstanceManager deploys and runs instances, RepositoryAgent queries repositories, and ImporterAgent plus ExporterAgent convert modpacks.

Trident As A CLI

This section is for modpack authors, server maintainers, and users who want to manage Minecraft instances from the terminal.

trident is the productized command-line entrypoint for Trident. It can create an instance from scratch, import existing modpacks, search and install packages, build launchable directories, log in accounts, run the game, and export the same instance into multiple modpack formats.

[](https://asciinema.org/a/1261198)

Use Cases

• Maintain a locally rebuildable Minecraft instance.
• Keep core modpack metadata in Git, then build and export releases from commands.
• Generate Trident, Modrinth, or CurseForge artifacts in CI.
• Chain scripts with JSON output, for example by piping package search results into install commands.
• Manage multiple instances, accounts, and repository configurations under one .trident home.

Installation

Install the CLI as a NuGet global tool:

dotnet tool install --global TridentCore.Cli

After installation, invoke the tool with the trident command:

trident --help

Update or uninstall it with:

dotnet tool update --global TridentCore.Cli
dotnet tool uninstall --global TridentCore.Cli

The examples below assume trident is already on PATH. If a newly installed tool is not found in the current shell, verify that the .NET global tools directory has been added to PATH.

Quick Start

trident create --identity cherry_picks --name "Cherry Picks" --version 1.21.1 --loader net.neoforged:21.1.200
trident add --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf
trident build --instance cherry_picks
trident run --instance cherry_picks --username Steve
trident instance export --instance cherry_picks --format modrinth --type online --author d3ara1n --output ./releases/cherry-picks.mrpack

Global Options

Global options are preprocessed before command dispatch and can appear anywhere in the command line.

| Option | Purpose | |-----------------------------------|---------------------------------------------------------------------------------------------------------------| | --home / --home= | Sets the Trident home directory and overrides automatic .trident discovery. | | --json | Forces structured JSON output. | | --no-interactive | Disables prompts, spinners, and progress UI; destructive commands also require --yes. | | --verbose | Enables information-level logs. | | --debug | Enables debug logs and full exceptions; also enables verbose output. | | --mcp | Starts Trident as an MCP (Model Context Protocol) server over stdio. Implies --json and --no-interactive. |

When stdout is redirected, the CLI automatically prefers JSON output for pipeline and scripting scenarios.

Command Overview

| Scenario | Commands | |-------------------|------------------------------------------------------------------------------------| | Instances | trident instance create/list/inspect/build/import/export/unlock/reset/delete/run | | Shortcuts | trident create/import/build/run/list/inspect | | Loaders | trident loader list/get/set, trident loader version list | | Packages | trident package list/search/add/inspect/enable/disable | | Package relations | trident package dependency list, trident package dependent list | | Package versions | trident package version list/set | | Package shortcuts | trident search, trident add | | Configuration | trident config list/get/set/unset | | Accounts | trident account list/add/remove | | Repositories | trident repository list/status/add/remove |

Commands that need an instance context resolve it in this order: --instance , --profile , then a managed profile.json in the current directory or one of its parents. Common short options include -I|--instance, -R|--repository, -v|--version, -n|--name, -i|--id, -l|--loader, -y|--yes, -A|--account, and -u|--username.

Workflow Examples

Create and build an instance:

trident create --identity vanilla --name "Vanilla 1.21.1" --version 1.21.1
trident build --instance vanilla --full-check

Import, run, and reset a modpack:

trident import --identity imported_pack --name "Imported Pack" ./modpack.zip
trident config set --name java.max_memory --value 8192
trident config set --instance imported_pack --name behavior.command.wrapper --value "prime-run {command}" --type string
trident run --instance imported_pack --username Steve --max-memory 6144
trident instance reset --instance imported_pack --yes

trident config without an instance manages CLI-global defaults in /.trident.cli/settings.json; --instance or --profile manages that instance's profile.json overrides. Launch options use command-line option > instance override > CLI-global setting > built-in default.

Search, install, and switch package versions:

trident package search --repository modrinth --kind mod --version 1.21.1 --loader net.neoforged "Mouse Tweaks"
trident package add --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf
trident package version list --version 1.21.1 --loader net.neoforged modrinth:aC3cM3Vq
trident package version set --instance cherry_picks modrinth:aC3cM3Vq@9I21YYxf

Pipe search results into an install command:

trident --json package search --repository modrinth --kind mod "Mouse Tweaks" \
  | trident --json --no-interactive package add --instance cherry_picks

Accounts and repositories:

trident account add --type offline --username Steve
trident account add --type microsoft
trident repository add --label modrinth-cn --driver modrinth --endpoint https://api.modrinth.com --user-agent "TridentCli"
trident repository status --label modrinth-cn

MCP Server

Trident can run as an MCP (Model Context Protocol) server, exposing its capabilities as tools to AI agents and MCP clients:

trident --mcp

The server communicates over stdio. Configure it in an MCP client (e.g. Claude Desktop, opencode):

{
  "mcpServers": {
    "trident": {
      "command": "trident",
      "args": ["--mcp"]
    }
  }
}

Available tools:

| Tool | Description | |------------------------------------------------|---------------------------------------------------------------| | List (InstanceTools) | List all Trident instances. | | Inspect (InstanceTools) | Inspect an instance with package preview. | | List (PackageTools) | List packages installed in an instance. | | Search (PackageTools) | Search packages in remote repositories or within an instance. | | Add (PackageTools) | Add a package to an instance by Pref. | | Inspect (PackageTools) | Inspect a package by Pref. | | SetEnabled (PackageTools) | Enable or disable an installed package. | | Get / Set / Unset / List (ConfigTools) | Manage configuration values. | | List / Status (RepositoryTools) | List repositories and check their status. | | List (AccountTools) | List registered accounts. | | List / VersionList (LoaderTools) | List supported loaders and query versions. |

All tools return JSON. The --home option is also respected in MCP mode.

Surface Boundaries

The MCP surface intentionally excludes operations that are irreversible, resource-heavy, involve external trust negotiation, or fire only zero-to-one times across the software lifecycle:

• Launching the game — trident run spawns a heavyweight process that holds CPU/GPU/memory and mutates saves; "the

game is already running" is not a state an agent can roll back.

• OAuth account login — Microsoft device-code login is a one-shot trust negotiation with the identity provider,

performed once in the GUI. An agent driving it gains nothing while touching credential lifecycle.

What belongs on the surface is the rest: reversible, idempotent, data-level operations such as package Prefs, version selection, dependency analysis, and import/export. This is a design contract, not a backlog — do not add launch or credential-lifecycle tools without raising it first.

CI/CD Modpack Publishing

Trident CLI can export the same instance into multiple release formats in GitHub Actions. The example below assumes the repository contains a .trident home managed by the CLI, or that the workflow supplies one through --home.

name: Build and Publish Modpack

on:
  push:
    tags:
      - v*

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install CLI
        run: dotnet tool install --global TridentCore.Cli

      - name: Export packs
        run: |
          trident instance export --format trident --type online --author d3ara1n --output Releases/trident.zip
          trident instance export --format curseforge --type online --author d3ara1n --output Releases/curseforge.zip
          trident instance export --format modrinth --type onli

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TridentCore](https://github.com/TridentCore)
- **Source:** [TridentCore/Trident.Net](https://github.com/TridentCore/Trident.Net)
- **License:** MIT

Install and usage instructions live in the source repository linked above.