Skip to content

📦 Economy — Model

🎯 Purpose

This folder contains the value types, enums, and shared helpers used across the Economy subsystem.

These types are public and are intended for use in gameplay code, UI, analytics, tests, and integrations.

They contain minimal shared logic (for example result helpers and sourceId construction), plus data contracts shared across economy flows.

🧩 What Lives Here

Value types

ChargeLine

Represents a single money line.

  • Fields: (id, amount)
  • id is trimmed and lowercased during construction
  • Validity is exposed via IsValid (id non-empty and amount > 0)
  • Used in PriceBundle.Money

ItemLine

Represents a single item line.

  • Fields: (guid, quantity)
  • guid is trimmed during construction
  • Validity is exposed via IsValid (guid non-empty and quantity > 0)
  • Used in PriceBundle.Items

PriceBundle

Bundle of optional money and/or item lines.

  • Structure:

  • IReadOnlyList<ChargeLine> Money

  • IReadOnlyList<ItemLine> Items

  • Helper factory methods:

  • MoneyOnly(moneyLines)

  • ItemsOnly(itemLines)
  • Used across economy flows

PriceBundle does not clone or freeze the provided lists. Callers should treat them as read-only; mutating them may affect consumers of the bundle.

A PriceBundle may contain:

  • Money only
  • Items only
  • Both money and items

Results

EcoOpResult

Represents the outcome of an economy operation.

Fields
  • Success — bool
  • Code — EcoOpCode
  • Message — optional string
Features
  • Factory helpers such as Ok(), Fail(), InvalidArgs(), ServiceMissing() and others
  • Deconstruction support
  • No implicit bool conversion
  • Equality and hashing support

Use EcoOpResult for branching on operation outcomes. Inspect Success, Code, or IsOk / IsFail.

Message is intended for diagnostics or UI and should not be used for gameplay branching.

EcoOpCode

Shared result codes used across Economy operations.

Examples include:

  • Ok
  • InvalidArgs
  • ServiceMissing
  • ContainerMissing
  • ResolverMissing
  • InsufficientFunds
  • NoSpace
  • NotOwned
  • PolicyBlocked
  • Overflow
  • EscrowUnavailable
  • UnknownError

EcoOpResultComparers

Reusable comparers for EcoOpResult.

  • ByCode — compares Success and Code, ignoring Message

Useful for:

  • Unit tests
  • Dictionaries and sets
  • Deduplicating results where message text is not relevant

Reasons and sources

EcoReasons

Shared reason strings for economy telemetry and logging.

Using consistent reason strings helps avoid fragmentation across systems.

EcoSource

Helper for building canonical sourceId strings.

  • Combines vendor and request identifiers
  • Trims whitespace
  • Replaces delimiter characters
  • Applies per-part length limits
  • Returns null when both inputs are empty

Validation and policies

LedgerPreflightMode

Controls UX preflight behaviour for IValueLedger.CanPay().

  • Strict
  • PolicyApproved

This affects preflight behaviour only. It does not change the authoritative behaviour of Pay().

Exact behaviour depends on the IValueLedger implementation.

🧠 Usage Guidance

  • Use PriceBundle to represent costs and payouts
  • Inspect EcoOpResult for branching on operation outcomes
  • Use shared reason values from EcoReasons for consistent telemetry
  • Use EcoSource when constructing sourceId values
  • Use EcoOpResultComparers.ByCode when message text is not relevant
  • Abstractions README
  • Facade README
  • Adapters README
  • Diagnostics README