# Modding SDK Guide

The modding SDK in `@aphrodite/game-dev-tools` provides a renderer-neutral
runtime contract for `.mayamod` packages, local development tools, and safe
engine API access.

## Package Format

Use `defineModManifest` to describe a mod package. A manifest includes the mod
ID, version, author, compatible game versions, dependencies, conflicts,
requested capabilities, scripts, assets, and metadata. `createModPackage`
combines that manifest with a root directory and file list for validation and
packaging.

`createModPackagePlan` produces the archive name, manifest path, included files,
and output path for `.mayamod` packaging.

## Runtime Loading

`createModRuntimeState` validates manifests, game-version compatibility,
dependency ranges, conflicts, and dependency cycles. Loaded mods are sorted with
dependencies before dependents, while disabled, blocked, and error states stay
visible through status records.

`createModLoadOrderViewModel` exposes load-order rows with dependency, conflict,
status, and move affordance data for editor or in-game management UI.
`moveModInLoadOrder` preserves dependency constraints, and `setModEnabled`
rebuilds runtime state after user changes.

## Sandbox and API

`createModSandboxPolicy` derives filesystem, network, memory, and capability
limits from a manifest. `evaluateModSandboxRequest` checks individual access
requests, and `invokeModApi` runs only registered endpoints whose required
capability is granted to the mod.

Use `createModApiRegistry` and `registerModApiEndpoint` to publish a curated API
surface for entity spawning, component edits, event listening, UI creation,
save-data access, mod-data writes, and asset loading.

## Scripts, Assets, and Hot Reload

`createModScriptPlans` maps Lua, WASM, and data scripts to runtime adapter
plans. `createModAssetCatalog` creates namespaced asset keys such as
`mod_id:asset_id` with absolute paths under each mod root.

`planModHotReload` compares changed files against registered mod roots, then
returns affected mod IDs, scripts that can reload in place, asset keys to
refresh, and mods that need unload/load cycles.

## Profiling and Error Isolation

`recordModPerformanceSample` and `createModPerformanceReports` summarize CPU and
memory use per mod against caller-provided budgets. `runModSafely` and
`captureModError` isolate runtime failures so one mod can be marked errored and
removed from load order without stopping the rest of the runtime.

## Toolkit and Documentation

`createModProjectTemplate` generates starter file contents and local package
commands. `generateModApiDocs` exports endpoint documentation from the runtime
registry, and `createModDevelopmentTutorials` lists built-in tutorial flows for
scripted mods, asset packs, and compatibility maintenance.
