SoHL Developer & API Documentation
The entry point for working on the Song of Heroic Lands (SoHL) system — for developers extending the API, contributors changing core, and anyone who needs a mental model of the code.
This documentation is developer- and API-facing only. Player- and GM-facing rules and play guides are not duplicated here — they live on the project site (see Player & GM rules below).
Start here
- Architecture Overview — the system’s mental model and a map of the
src/tree. Read this first. - Getting Started — environment setup, codebase tour, and your first change.
- API Reference — generated TypeDoc, with a sidebar grouped to mirror the source: Core / Documents / Domain / Utility.
Security-critical change? If you are touching serialization, HTML rendering, actions/executors, or chat/cross-client flows, read Security Model & Guardrails first. Its keystone rule — data carries a reference to code (a
__kindtag, a method name, a Macro UUID), never source; functions are never serialized — is the system’s top security constraint.
Concepts
Design and rationale — how and why the system is built the way it is.
- Architecture Overview — the mental model and a map of the
src/tree. Read this first. - The SoHL API
- Combat Model — assisted vs. automated combat, and how the combat flow is wired programmatically (combatants, the exchange workflow, resolution).
- Macros and Actions
- Expressions and Scripts — the ways author-supplied logic runs:
SafeExpression, Macros, and the Expression Library. - Security Model & Guardrails — the threat model and the standing rules every change must respect. Read before touching serialization, HTML rendering, actions, or cross-client flows.
- CSS Architecture & Styleguide
How-to
Task-oriented guides for getting something done.
- Getting Started (New Developer Guide)
- Extension Points
- API Access Map
- Lifecycle Hooks
- House Rules Cookbook
- Testing
- Build, Deployment, and Release
- Issue Reporting — how issues are typed, prioritized, labeled, and tied to capability milestones.
Reference
Contracts, catalogs, and specifications.
- Type Catalog
- Modifier Model
- Combat Resolution Pipeline
- Body Structure
- Effects Integration
- Runtime Contracts
- Scene, Token, and Combatant Systems
- Calendar
- Event Queue
Contributing
How to contribute: standards, the development workflow, and maintainer/project-meta.
- System Development — standards, the rules of development, and how to submit a change.
- Writing Modules — build a Foundry module that extends SoHL without forking.
- Writing Changesets — record a change for the changelog and release notes.
- API Docs Hosting (api.heroiclands.org)
Player & GM rules (external)
Rules and play guides are maintained on the project site, not in this repo: