API Reference Overview

This section provides comprehensive documentation for all Mod-Engine APIs, types, and functions.

Core API

Configuration

• defineConfig() - Define system configuration
• createEngine() - Create engine instance
• validateConfig() - Validate configuration

Engine

• engine.builder() - Create item builder
• engine.evaluate() - Evaluate item
• createConditionBuilder() - Create condition builder

Builder

• .set() - Set item attributes
• .increase() - Add increase modifier
• .multiply() - Add multiply modifier
• .when() - Add condition
• .with() - Set modifier options
• .build() - Build item specification

Type System

Core Types

• ConfigSpec - Configuration specification
• ItemSpec - Item specification
• EvaluationResult - Evaluation output

Modifier Types

• Modifier - Modifier specification
• Condition - Conditional logic
• Stacking - Stacking behavior

Attribute Types

• AttributeSchema - Attribute definition
• EnumAttributeSchema - Enum attribute
• NumberAttributeSchema - Number attribute
• BooleanAttributeSchema - Boolean attribute

Operations

Built-in Operations

• sum - Addition operation
• subtract - Subtraction operation
• multiply - Multiplication operation

Custom Operations

• OperationImpl - Operation implementation type
• engine.registerOperation() - Register a custom operation implementation

Validation

Validation Functions

• validateItem() - Validate item specification
• validateCondition() - Validate condition
• validateOperations() - Validate operations

Error Types

• ValidationError - Validation failure
• SchemaError - Schema validation error
• ConditionError - Condition validation error

Serialization

Serialization Functions

• serializeItem() - Serialize item to JSON
• deserializeItem() - Deserialize item from JSON
• toSnapshot() - Create evaluation snapshot

Quick Reference

Common Patterns

Basic Configuration

import { defineConfig, createEngine } from "mod-engine";

const config = defineConfig({
  metrics: ["Health", "Damage"] as const,
  operations: ["sum", "multiply"] as const,
  attributes: [
    /* ... */
  ] as const,
});

const engine = createEngine(config);

Building Items

const item = engine
  .builder("Item Name")
  .set("attribute", value)
  .increase("metric")
  .by(amount)
  .when(condition)
  .build();

Evaluation

const result = engine.evaluate(item);
console.log(result.metrics);
console.log(result.appliedModifiers);

Type Utilities

Inference Types

• MetricOf<TConfig> - Extract metric types from config
• AttrKeyOf<TConfig> - Extract attribute keys from config
• AttrValueOf<TConfig, TKey> - Extract attribute value type
• OperationOf<TConfig> - Extract operation types from config

Example Usage

type Config = typeof myConfig;
type Metrics = MetricOf<Config>; // "Health" | "Damage"
type Operations = OperationOf<Config>; // "sum" | "multiply"

Error Handling

All Mod-Engine functions throw typed errors that you can catch and handle:

import { ValidationError, SchemaError } from "mod-engine";

try {
  const result = engine.evaluate(item);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Validation failed:", error.message);
  } else if (error instanceof SchemaError) {
    console.error("Schema error:", error.message);
  }
}

Next Steps

• Browse detailed API documentation for each function
• See practical examples of API usage
• Learn about concepts and patterns