### Install NDS-API Go SDK

Source: https://github.com/misty4119/nds-api/blob/main/Go/README.md

Command to install the NDS-API Go SDK using the go get command. This command fetches and installs the specified version of the SDK into your Go workspace.

```bash
go get github.com/misty4119/nds-api/Go@v3.0.4
```

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

### Quick Start: Decimal Handling in Go

Source: https://github.com/misty4119/nds-api/blob/main/Go/README.md

Example demonstrating how to create and use a Decimal type from the NDS common package in Go. This snippet shows basic instantiation and retrieval of the Decimal value.

```go
package main

import (
	"fmt"

	"github.com/misty4119/nds-api/Go/nds/common"
)

func main() {
	d := &common.Decimal{Value: "1.23", Scale: 2}
	fmt.Println(d.GetValue())
}
```

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

### Install NDS API C# SDK

Source: https://github.com/misty4119/nds-api/blob/main/docs/CSHARP_SDK.md

Installs the Noie.Nds.Api NuGet package version 2.0.0. This command requires the .NET SDK 10.0 or higher.

```bash
dotnet add package Noie.Nds.Api --version 2.0.0
```

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

### Install NDS-API Package in .NET (C#)

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Instructions for adding the NDS-API package to a .NET project using the NuGet package manager. An option to install only abstractions is also provided.

```bash
dotnet add package Noie.Nds.Api
```

```bash
dotnet add package Noie.Nds.Api.Abstractions
```

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

### Install Noie.Nds.Api Package

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Installs the full implementation of the Noie.Nds.Api package using the .NET CLI. This package includes protocol support for NDS-API.

```bash
dotnet add package Noie.Nds.Api
```

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

### Install Noie.Nds.Api.Abstractions Package

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Installs the abstractions package for Noie.Nds.Api using the .NET CLI. This package contains core interfaces and types without the full protocol implementation.

```bash
dotnet add package Noie.Nds.Api.Abstractions
```

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

### Initial Project Setup and Build Commands

Source: https://github.com/misty4119/nds-api/blob/main/CONTRIBUTING.md

This snippet provides the essential bash commands for cloning the NDS-API repository, navigating into the project directory, linting protocol specifications, building the Java and C# projects, and running tests for both languages.

```bash
git clone https://github.com/Misty4119/nds-api.git
cd nds-api

buf lint spec/proto
./gradlew :java:build
dotnet build csharp/

./gradlew :java:test && dotnet test csharp/
```

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

### Install NDS-API Ruby Gem

Source: https://github.com/misty4119/nds-api/blob/main/Ruby/README.md

Installs the noie-nds-api gem with version 3.0.4. This is the primary method for integrating the SDK into a Ruby project.

```bash
gem install noie-nds-api -v 3.0.4
```

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

### Install Nds-Api TypeScript SDK

Source: https://github.com/misty4119/nds-api/blob/main/TypeScript/README.md

Installs the NDS-API TypeScript SDK version 3.0.4 using npm. This command is used to add the SDK as a dependency to your project.

```bash
npm i @misty4119/nds-api@3.0.4
```

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

### NDS API Installation and Package Management

Source: https://context7.com/misty4119/nds-api/llms.txt

Provides commands for installing the NDS API across various programming languages and package managers. This includes Gradle, Maven, .NET CLI, npm, pip, cargo, and gem.

```bash
# Java (Gradle Kotlin)
# build.gradle.kts
dependencies {
    implementation("io.github.misty4119:noiedigitalsystem-api:3.0.6")
}

# Java (Maven)
# pom.xml
<dependency>
    <groupId>io.github.misty4119</groupId>
    <artifactId>noiedigitalsystem-api</artifactId>
    <version>3.0.6</version>
</dependency>

# .NET (C#)
dotnet add package Noie.Nds.Api --version 3.0.6
# Or for interfaces only:
dotnet add package Noie.Nds.Api.Abstractions --version 3.0.6

# TypeScript
npm install @misty4119/nds-api

# Python
pip install noie-nds-api

# Rust
cargo add noie-nds-api

# Ruby
gem install noie-nds-api
```

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

### Quick Start: Create a Decimal Object in Ruby

Source: https://github.com/misty4119/nds-api/blob/main/Ruby/README.md

Demonstrates how to create and use a Decimal object from the NDS API Ruby SDK. It requires the 'noie_nds_api' library to be required.

```ruby
require "noie_nds_api"

d = Nds::Common::Decimal.new(value: "1.23", scale: 2)
puts d.value
```

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

### Conventional Commit Examples

Source: https://github.com/misty4119/nds-api/blob/main/CONTRIBUTING.md

Provides practical examples of commit messages following the Conventional Commits specification for the NDS-API project. These examples demonstrate how to use different types and scopes to describe changes effectively.

```git
feat(spec): add TransactionStatus enum to transaction.proto
feat(java): implement TransactionAdapter for proto conversion
feat(csharp): add INdsTransaction abstraction
chore(ci): update .NET SDK to 10.0
```

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

### Install NDS-API Dependency in Java

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Instructions for adding the NDS-API dependency to a Java project using Maven Central. Ensure you use the latest published version.

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.misty4119:noiedigitalsystem-api:<VERSION>")
}
```

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

### Build Java SDK Locally

Source: https://github.com/misty4119/nds-api/blob/main/docs/JAVA_SDK.md

Command to build the Java SDK locally using Gradle. This command compiles and packages the SDK, useful for development or testing.

```bash
./gradlew :java:build
```

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

### Convert Money to Protocol Buffer in C#

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Example of converting a decimal amount to the Money protocol buffer format using MoneyAdapter in C#. This is useful for working with v3 fixed-point protocol amounts.

```csharp
using Nds.Ledger.V1;
using Noie.Nds.Api.Adapter;

Money money = MoneyAdapter.ToProto("NDS", 100.5m);
decimal amount = MoneyAdapter.FromProto(money);
```

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

### Quick Start: Decimal Type in Python

Source: https://github.com/misty4119/nds-api/blob/main/Python/README.md

Demonstrates how to create and use a Decimal type from the NDS-API Python SDK. It imports the necessary protobuf definition and initializes a Decimal object with a value and scale.

```python
from nds.common import common_pb2

d = common_pb2.Decimal(value="1.23", scale=2)
print(d.value)
```

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

### Install NDS-API Python SDK

Source: https://github.com/misty4119/nds-api/blob/main/Python/README.md

Installs a specific version of the noie-nds-api Python package using pip. This command ensures you have the correct version of the NDS-API Protocol Buffers Data Transfer Objects.

```bash
pip install noie-nds-api==3.0.4
```

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

### Add Gradle Dependency for Java SDK (Kotlin)

Source: https://github.com/misty4119/nds-api/blob/main/docs/JAVA_SDK.md

This snippet demonstrates how to include the noiedigitalsystem-api artifact in a Gradle project using Kotlin DSL. Verify your Gradle setup and Java version compatibility.

```kotlin
dependencies {
  implementation("io.github.misty4119:noiedigitalsystem-api:2.0.0")
}
```

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

### Installing NDS API Protobuf Library with CMake

Source: https://github.com/misty4119/nds-api/blob/main/Cpp/CMakeLists.txt

This code defines the installation rules for the 'noie_nds_api_proto' target using CMake's GNUInstallDirs module. It specifies the destinations for the library archives, shared libraries, and runtime binaries, as well as installing the generated header files.

```cmake
include(GNUInstallDirs)
install(TARGETS noie_nds_api_proto
  EXPORT noie_nds_api_protoTargets
  ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
  LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
  RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
)
install(DIRECTORY "${CMAKE_CURRENT_LIST_DIR}/src/" DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
```

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

### Install NDS-API Ruby Gem

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Command to install the NDS-API Ruby gem. This package provides generated protocol types for use in Ruby projects.

```bash
gem install noie-nds-api
```

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

### Install NDS-API TypeScript Package

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Command to install the NDS-API TypeScript package from npm. This package provides generated protocol types for use in TypeScript projects.

```bash
npm i @misty4119/nds-api
```

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

### Build and Test NDS API C# SDK Locally

Source: https://github.com/misty4119/nds-api/blob/main/docs/CSHARP_SDK.md

Builds and tests the C# SDK locally in Release configuration. Requires the .NET SDK 10.0 or higher.

```bash
dotnet build csharp/ --configuration Release
dotnet test csharp/ --configuration Release
```

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

### Install NDS-API Python Package

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Command to install the NDS-API Python package from PyPI using pip. This package provides generated protocol types for use in Python projects.

```bash
pip install noie-nds-api
```

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

### Install NDS-API Rust Crate

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Command to add the NDS-API Rust crate as a dependency to a Cargo project. This provides generated protocol types for use in Rust applications.

```bash
cargo add noie-nds-api
```

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

### Consume NDS-API C++ SDK with CMake FetchContent

Source: https://github.com/misty4119/nds-api/blob/main/Cpp/README.md

Example CMake code to include the NDS-API C++ SDK in a project using FetchContent. It declares the dependency, makes it available, adds an executable, and links the library.

```cmake
include(FetchContent)
FetchContent_Declare(nds_api
  GIT_REPOSITORY https://github.com/Misty4119/nds-api.git
  GIT_TAG v3.0.4
)
FetchContent_MakeAvailable(nds_api)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE noie_nds_api_proto)
```

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

### Handle Results in C#

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Demonstrates how to handle structured results from runtime implementations in C#. It shows creating both successful and failure results using NdsResult.

```csharp
using Noie.Nds.Api.Result;

var ok = NdsResult<int>.Success(1);
var fail = NdsResult<int>.Failure("VALIDATION_INVALID_ARGUMENT", "bad input");
```

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

### Install NDS-API Java SDK using Gradle

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Instructions for adding the NDS-API Java SDK dependency to a Gradle project. It requires configuring the mavenCentral() repository and specifying the implementation dependency with the latest version.

```kotlin
repositories {
    mavenCentral()
}
dependencies {
    implementation("io.github.misty4119:noiedigitalsystem-api:<VERSION>")
}
```

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

### Add Maven Dependency for Java SDK

Source: https://github.com/misty4119/nds-api/blob/main/docs/JAVA_SDK.md

This snippet shows how to add the noiedigitalsystem-api artifact as a dependency in a Maven project. Ensure you are using a compatible version of the Java SDK.

```xml
<dependency>
  <groupId>io.github.misty4119</groupId>
  <artifactId>noiedigitalsystem-api</artifactId>
  <version>2.0.0</version>
</dependency>
```

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

### Install NDS-API SDK with Cargo

Source: https://github.com/misty4119/nds-api/blob/main/Rust/README.md

This code snippet demonstrates how to add the noie-nds-api crate as a dependency to your Rust project using Cargo.  It specifies the crate name and version to be included in your project's dependencies.

```bash
cargo add noie-nds-api@3.0.4
```

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

### Install NDS-API Java SDK using Maven

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Instructions for adding the NDS-API Java SDK dependency to a Maven project. It involves specifying the groupId, artifactId, and version in the dependency management section.

```xml
<dependency>
  <groupId>io.github.misty4119</groupId>
  <artifactId>noiedigitalsystem-api</artifactId>
  <version><!-- see Maven Central --></version>
</dependency>
```

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

### Create Decimal Object in TypeScript

Source: https://github.com/misty4119/nds-api/blob/main/TypeScript/README.md

Demonstrates how to create a Decimal object using the ndsCommon module from the NDS-API TypeScript SDK. The Decimal type includes a 'value' and 'scale' property. This is a basic usage example for handling decimal values within the SDK.

```typescript
import { ndsCommon } from "@misty4119/nds-api";

const d: ndsCommon.Decimal = { value: "1.23", scale: 2 };
console.log(d.value);
```

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

### Create NDS Policy and Rationale

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Shows how to create an NDS Policy object with a name and type, and an NDS Rationale object with source and thought path, using Noie.Nds.Api.Policy and Noie.Nds.Api.Audit namespaces.

```csharp
using Noie.Nds.Api.Policy;
using Noie.Nds.Api.Audit;

var policy = NdsPolicy.Of("shop-default-policy-v1", "quota");
var rationale = NdsRationale.Of(
    source: "human_admin",
    thoughtPath: new[] { "manual_review", "approved" }
);
```

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

### Resume Token Handling

Source: https://github.com/misty4119/nds-api/blob/main/spec/docs/V3.md

Details on how to use and handle resume tokens for state synchronization, including expiration scenarios and fallback mechanisms.

```APIDOC
## Resume Token Handling

### Description
This section details the requirements and behavior related to resume tokens, which are essential for clients to synchronize state with the server. It covers the nature of these tokens, client and server responsibilities, and the specific error responses when a token expires.

### Server Requirements
- Servers MUST issue opaque `ResumeToken` / `Cursor` tokens.
- Servers MUST define replay retention policies and error behavior for expired tokens.

### Client Requirements
- Clients MUST use server-issued tokens and MUST NOT construct them.

### Token Expiration
When a resume token cannot be honored, the server MUST return the following error:

- `ErrorStatus.code = "SYNC_RESUME_TOKEN_EXPIRED"`
- `ErrorStatus.category = "ERROR_CATEGORY_RETRYABLE"`

The server MUST include machine-readable fallback hints in `ErrorStatus.details`:

- `fallback_strategy`: (string) One of `since` or `full_snapshot`.
- `fallback_since_unix_millis`: (integer) UTC milliseconds since epoch (required when `fallback_strategy=since`).
- `replay_window_seconds`: (integer) Server replay retention window in seconds (optional).
```

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

### Get NDS Runtime Instance (Java)

Source: https://github.com/misty4119/nds-api/blob/main/MINECRAFT_DEVELOPER_GUIDE.md

Retrieves the NDS API runtime instance within a Java Minecraft plugin. It checks if the NDS runtime is initialized before obtaining the instance, disabling the plugin if initialization fails.

```java
import noie.linmimeng.noiedigitalsystem.api.NdsProvider;
import noie.linmimeng.noiedigitalsystem.api.NdsRuntime;

public final class MyPlugin extends JavaPlugin {
  private NdsRuntime runtime;

  @Override
  public void onEnable() {
    if (!NdsProvider.isInitialized()) {
      getLogger().severe("NDS runtime is not initialized.");
      getServer().getPluginManager().disablePlugin(this);
      return;
    }
    runtime = NdsProvider.get();
  }
}
```

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

### Apply Value Change Transaction (Java)

Source: https://github.com/misty4119/nds-api/blob/main/MINECRAFT_DEVELOPER_GUIDE.md

Applies a value change to a player's asset balance using a transaction. This example deducts 100 'coins' for a shop purchase, specifying strong consistency and a reason. It handles the transaction result asynchronously.

```java
import java.math.BigDecimal;
import noie.linmimeng.noiedigitalsystem.api.transaction.NdsTransaction;
import noie.linmimeng.noiedigitalsystem.api.transaction.NdsTransactionBuilder;
import noie.linmimeng.noiedigitalsystem.api.transaction.ConsistencyMode;

NdsTransaction tx = NdsTransactionBuilder.create()
  .actor(playerIdentity)
  .asset(coins)
  .delta(BigDecimal.valueOf(-100))  // negative = deduct
  .consistency(ConsistencyMode.STRONG)
  .reason("SHOP_PURCHASE")
  .build();

runtime.eventBus().publish(tx)
  .thenAcceptAsync(result -> {
    if (result.isSuccess()) {
      player.sendMessage("Purchase OK");
    } else {
      player.sendMessage("Purchase failed: " + result.error().message());
    }
  }, runtime.defaultExecutor());
```

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

### Create and Parse NDS Identity

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Demonstrates creating an NDS Identity object for a player and parsing an identity string into an NDS Identity object using the Noie.Nds.Api.Identity namespace.

```csharp
using Noie.Nds.Api.Identity;

// Create player identity
var player = NdsIdentity.Of("550e8400-e29b-41d4-a716-446655440000", IdentityType.Player);

// Parse from string
var identity = NdsIdentity.FromString("PLAYER:550e8400-e29b-41d4-a716-446655440000");
```

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

### Create and Enriched NDS Context

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Demonstrates creating a new NDS Context for tracing and adding metadata to it using the Noie.Nds.Api.Context namespace.

```csharp
using Noie.Nds.Api.Context;

// Create context for tracing
var context = NdsContext.Create();
Console.WriteLine($"TraceId: {context.TraceId}");

// Add metadata
var enriched = context.WithMeta("user", "player123");
```

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

### Local Protocol Verification using Buf and Gradle/Dotnet

Source: https://github.com/misty4119/nds-api/blob/main/README.md

Commands to locally verify the Protocol Buffers schema using 'buf lint' and then build the Java SDK and run .NET tests. This is useful when vendoring the protocol definitions.

```bash
cd spec/proto
buf lint

cd ../..
.\gradlew.bat :java:build
dotnet test .\csharp\Noie.Nds.sln -c Release
```

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

### Fetching Protobuf with FetchContent in CMake

Source: https://github.com/misty4119/nds-api/blob/main/Cpp/CMakeLists.txt

This code block configures the 'FetchContent' module to download and build the Protobuf library from a specified Git tag. It sets various build options for Protobuf to minimize its build size and ensures the correct tag is used, matching the version of the generated protobuf sources.

```cmake
include(FetchContent)
set(NDS_API_PROTOBUF_TAG "v33.5" CACHE STRING "protobuf git tag for FetchContent")

set(protobuf_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(protobuf_BUILD_CONFORMANCE OFF CACHE BOOL "" FORCE)
set(protobuf_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
set(protobuf_BUILD_PROTOC_BINARIES OFF CACHE BOOL "" FORCE)

FetchContent_Declare(protobuf
  GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
  GIT_TAG "${NDS_API_PROTOBUF_TAG}"
  GIT_SHALLOW TRUE
)

set(protobuf_INSTALL OFF CACHE BOOL "" FORCE)
set(protobuf_BUILD_PROTOBUF_BINARIES ON CACHE BOOL "" FORCE)

FetchContent_MakeAvailable(protobuf)
```

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

### Create AssetId in Java and C#

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Shows how to create an AssetId object, which identifies a value being modified, independent of its storage, in Java and C#.

```java
import noie.linmimeng.noiedigitalsystem.api.asset.AssetId;
import noie.linmimeng.noiedigitalsystem.api.asset.AssetScope;

AssetId coins = AssetId.of(AssetScope.PLAYER, "coins");
```

```csharp
using Noie.Nds.Api.Asset;

var coins = AssetId.Player("coins");
```

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

### Create and Parse NDS Asset IDs

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Shows how to create AssetId objects for player-specific and server-specific assets, as well as parsing an asset ID string using the Noie.Nds.Api.Asset namespace.

```csharp
using Noie.Nds.Api.Asset;

// Create asset IDs
var coins = AssetId.Player("coins");
var bossHp = AssetId.Server("world_boss_hp");

// Parse from string
var asset = AssetId.FromString("player:gold");
```

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

### Create NDS Identity in Java and C#

Source: https://github.com/misty4119/nds-api/blob/main/DEVELOPER_GUIDE.md

Demonstrates how to create an NDS Identity object, representing a principal performing an action, in both Java and C#.

```java
import noie.linmimeng.noiedigitalsystem.api.identity.NdsIdentity;
import noie.linmimeng.noiedigitalsystem.api.identity.IdentityType;

NdsIdentity actor = NdsIdentity.of("system:shop", IdentityType.SYSTEM);
```

```csharp
using Noie.Nds.Api.Identity;

var actor = NdsIdentity.Of("system:shop", IdentityType.System);
```

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

### Build C++ Project with CMake

Source: https://github.com/misty4119/nds-api/blob/main/Cpp/README.md

Instructions for building the C++ project using CMake. This involves configuring the build directory and then building the project with parallel jobs.

```bash
cmake -S Cpp -B Cpp/build
cmake --build Cpp/build -j
```

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

### v3 Sync Protocol - Streaming and Synchronization (Protobuf)

Source: https://context7.com/misty4119/nds-api/llms.txt

Defines data structures for the v3 Sync Protocol, enabling event stream subscriptions and balance watching with features like resume tokens, backpressure control, and delta updates for efficient streaming.

```protobuf
// Proto definition: spec/proto/nds/sync/v1/sync.proto

// Subscribe to event stream with flow control
message SubscribeEventsRequest {
  optional ResumeToken resume = 1;              // Continue from position
  optional google.protobuf.Timestamp since = 2; // Fallback start time
  repeated nds.event.v1.EventType types = 3;    // Filter by event types
  optional nds.identity.v1.PersonaId owner = 4; // Filter by owner
  int32 max_events_per_second = 10;             // Rate limit hint
  optional int32 max_in_flight = 11;            // Backpressure hint
  optional int32 page_size = 12;                // Batch size hint
}

// Watch balance changes (delta updates preferred)
message WatchBalanceRequest {
  nds.ledger.v1.BalanceKey key = 1;
  optional ResumeToken resume = 2;
  int32 max_updates_per_second = 10;
  optional int32 max_in_flight = 11;
}

// Delta update for efficient streaming
message BalanceDelta {
  nds.ledger.v1.BalanceKey key = 1;
  nds.ledger.v1.Money delta = 2;     // Change amount
  uint64 new_version = 3;            // New version after change
  nds.event.v1.Cursor cursor = 4;    // Stream position
  bytes proof_tx_id = 5;             // Transaction proof
}

```

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

### Create and Enrichen Context (Java)

Source: https://github.com/misty4119/nds-api/blob/main/java/README.md

Demonstrates the creation of a new NdsContext and how to add metadata to it using the withMeta method, showing the traceId of the context.

```java
import noie.linmimeng.noiedigitalsystem.api.context.NdsContext;

var ctx = NdsContext.create();
System.out.println("TraceId: " + ctx.traceId());

var enriched = ctx.withMeta("user", "player123");
```

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

### NDS Result Pattern Usage

Source: https://github.com/misty4119/nds-api/blob/main/csharp/README.md

Illustrates creating success and failure NDS Result objects, performing functional chaining with Map, OnSuccess, and OnFailure, and using pattern matching with Match. Requires Noie.Nds.Api.Result namespace.

```csharp
using Noie.Nds.Api.Result;

// Create results
var success = NdsResult<int>.Success(100);
var failure = NdsResult<int>.Failure("INSUFFICIENT_BALANCE", "Not enough coins");

// Functional chaining
var result = success
    .Map(x => x * 2)
    .OnSuccess(x => Console.WriteLine($"Value: {x}"))
    .OnFailure(e => Console.WriteLine($"Error: {e.Message}"));

// Pattern matching
var message = result.Match(
    onSuccess: x => $"Got {x}",
    onFailure: e => $"Failed: {e.Code}"
);
```

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

### Add NDS-API Dependency (Gradle Kotlin)

Source: https://github.com/misty4119/nds-api/blob/main/MINECRAFT_DEVELOPER_GUIDE.md

Configures the Gradle build script to include NDS-API as a provided dependency for a Minecraft plugin. This ensures the API is available at runtime without being bundled, preventing conflicts.

```kotlin
repositories {
    mavenCentral()
}

dependencies {
    compileOnly("io.github.misty4119:noiedigitalsystem-api:<VERSION>")
}
```

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

### Add NDS-API Dependency (Maven)

Source: https://github.com/misty4119/nds-api/blob/main/MINECRAFT_DEVELOPER_GUIDE.md

Configures the Maven project object model (pom.xml) to include NDS-API as a provided dependency. This is crucial for Minecraft plugins to utilize the API at runtime without packaging it, avoiding versioning issues.

```xml
<dependency>
  <groupId>io.github.misty4119</groupId>
  <artifactId>noiedigitalsystem-api</artifactId>
  <version><!-- see Maven Central --></version>
  <scope>provided</scope>
</dependency>
```

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

### Create Identity and Asset IDs (Java)

Source: https://github.com/misty4119/nds-api/blob/main/MINECRAFT_DEVELOPER_GUIDE.md

Demonstrates how to create NDS Identity objects from Bukkit UUIDs and AssetId objects for specific in-game assets like 'coins'. These are fundamental for interacting with the NDS API for player-specific data.

```java
import noie.linmimeng.noiedigitalsystem.api.asset.AssetId;
import noie.linmimeng.noiedigitalsystem.api.asset.AssetScope;
import noie.linmimeng.noiedigitalsystem.api.identity.NdsIdentity;

NdsIdentity playerIdentity = NdsIdentity.fromString(player.getUniqueId().toString());
AssetId coins = AssetId.of(AssetScope.PLAYER, "coins");
```

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

### Use Decimal Type in Rust

Source: https://github.com/misty4119/nds-api/blob/main/Rust/README.md

This Rust code snippet demonstrates the usage of the Decimal struct from the noie_nds_api crate. It initializes a Decimal object with a value and scale, and then prints the value to the console. This showcases a basic example of how to use the provided data types.

```rust
use noie_nds_api::nds::common::Decimal;

let d = Decimal {
    value: "1.23".to_string(),
    scale: 2,
};

println!("{}", d.value);
```

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

### Create and Parse Asset IDs (Java)

Source: https://github.com/misty4119/nds-api/blob/main/java/README.md

Shows how to create AssetIds for different scopes (PLAYER, SERVER) and how to parse an AssetId from its string representation using the AssetId class.

```java
import noie.linmimeng.noiedigitalsystem.api.asset.AssetId;
import noie.linmimeng.noiedigitalsystem.api.asset.AssetScope;

// Create asset IDs
var coins = AssetId.of(AssetScope.PLAYER, "coins");
var bossHp = AssetId.of(AssetScope.SERVER, "world_boss_hp");

// Parse from string
var asset = AssetId.fromString("player:gold");
```

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

### Convert Between BigDecimal and Money Proto (Java)

Source: https://context7.com/misty4119/nds-api/llms.txt

Demonstrates converting between Java's BigDecimal and the v3 fixed-point Money protocol representation using the MoneyAdapter. It covers exact conversions, zero and negative values, and error handling for invalid inputs like excessive fractional digits or empty currency codes. No external dependencies beyond the NDS API library are required.

```java
// Java - Converting between BigDecimal and Money proto
import noie.linmimeng.noiedigitalsystem.api.adapter.MoneyAdapter;
import noie.linmimeng.noiedigitalsystem.api.proto.ledger.v1.Money;
import java.math.BigDecimal;

// Convert BigDecimal to proto Money (exact; no rounding)
BigDecimal amount = new BigDecimal("100.500000000");  // up to 9 decimal places
Money proto = MoneyAdapter.toProto("NDS", amount);
// proto.getUnits() = 100, proto.getNanos() = 500000000, proto.getCurrencyCode() = "NDS"

// Convert proto Money back to BigDecimal (exact)
BigDecimal converted = MoneyAdapter.fromProto(proto);  // 100.500000000

// Zero values
Money zero = MoneyAdapter.toProto("NDS", BigDecimal.ZERO);
// units=0, nanos=0

// Negative values (sign must be consistent)
Money negative = MoneyAdapter.toProto("NDS", new BigDecimal("-50.25"));
// units=-50, nanos=-250000000

// Error cases
try {
    // More than 9 fractional digits - throws IllegalArgumentException
    MoneyAdapter.toProto("NDS", new BigDecimal("1.1234567890"));
} catch (IllegalArgumentException e) {
    System.err.println("Exact conversion required: " + e.getMessage());
}

try {
    // Empty currency code - throws IllegalArgumentException
    MoneyAdapter.toProto("", BigDecimal.ONE);
} catch (IllegalArgumentException e) {
    System.err.println("Currency required: " + e.getMessage());
}

```

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

### Working with NdsResult in Java

Source: https://context7.com/misty4119/nds-api/llms.txt

Demonstrates how to create, check, and chain NdsResult objects in Java. It covers success and failure states, functional mapping, flat mapping, and handling results with callbacks or converting to Optional. Requires the noie.linmimeng.noiedigitalsystem.api.result package.

```java
import noie.linmimeng.noiedigitalsystem.api.result.NdsResult;
import noie.linmimeng.noiedigitalsystem.api.result.NdsError;
import java.util.Optional;

// Create results
NdsResult<Integer> success = NdsResult.success(100);
NdsResult<Integer> failure = NdsResult.failure("INSUFFICIENT_BALANCE", "Not enough coins");
NdsResult<Integer> failureWithError = NdsResult.failure(NdsError.of("VALIDATION_ERROR", "Invalid amount"));

// Check and access
if (success.isSuccess()) {
    int value = success.data();  // 100
}

// Functional chaining
NdsResult<String> mapped = success
    .map(n -> n * 2)                    // NdsResult<Integer> with 200
    .map(n -> "Balance: " + n);         // NdsResult<String> with "Balance: 200"

// FlatMap for operations that return Result
NdsResult<Integer> chained = success.flatMap(balance ->
    balance >= 50
        ? NdsResult.success(balance - 50)
        : NdsResult.failure("INSUFFICIENT_BALANCE", "Need at least 50")
);

// Handle success/failure with callbacks
success
    .onSuccess(data -> System.out.println("Got: " + data))
    .onFailure(error -> System.err.println("Error: " + error.code()));

// Convert to Optional
Optional<Integer> optional = success.toOptional();
```