Developer 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

1. Architecture Overview — the system’s mental model and a map of the src/ tree. Read this first.
2. Getting Started — environment setup, codebase tour, and your first change.
3. 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 __kind tag, 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
• Action Cards & the Consent Model — the universal pattern every automated interaction is built on: self-sufficient actions offered across the chat log, run only at a human’s behest. Read before adding any cross-client flow.
• 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
• Writing Guided Tours — the SohlTour framework: step kinds, value/action gates, sheet navigation, and how to register a tour.
• Testing
• Build, Deployment, and Release
• Issue Reporting — how issues are typed, prioritized, labeled, and tied to capability milestones.

Content Creator

Authoring the content notes in assets/content/ that compile into compendium documents — for the person writing notes rather than changing the system.

• Content Creator — the section landing: what a content note is, and which page answers which question.
• The Authoring Workflow — where content lives, the frontmatter every note carries whatever its type, and how a note becomes a compendium document. Read this first.
• Item Note Frontmatter — the generated per-type field reference for all 13 item types: every sohl: field, its shape, requiredness, and default.
• Actor Notes — authoring a being, and the (type, shortcode) address space its embedded items resolve through.
• Map Notes — authoring a Foundry Scene as a markdown note: the battlemap / localmap / regionalmap schema, the two unit conventions, regions and their behaviours, and how a map is packaged.
• Authoring a Macro Content Note — how a type: macro note compiles into a Foundry Macro plus its documentation, and what the {#script} anchor does.
• Linking Between Content Notes — wikilinks for content authors: the four forms, and why an item and its documentation need two different addresses.
• Asset Conventions — where art files live, how img: resolves to a shipped path, image and SVG standards, and default item art.
• Generated Content Tables — Dataview TABLE queries that tabulate content notes from their frontmatter.

Reference

Contracts, catalogs, and specifications.

• Type Catalog
• The Link Manifest — the cross-package index: canonical addresses, Foundry UUIDs and anchors, and what a consuming build must do with them.
• Modifier Model
• Combat Resolution Pipeline
• Result-description Tables
• Body Structure
• Effects Integration
• Runtime Contracts
• World Migration Runner
• Shortcode Integrity
• Scene, Token, and Combatant Systems
• Calendar
• Event Queue
• Randomness
• Handlebars Template Helpers
• Localization Keys — the naming standard for lang/en.json: namespaces, group and leaf case, what may never appear in a key, and why keys are permanent.

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.

Player & GM rules (external)

Rules and play guides are maintained on the project site, not in this repo:

• SoHL on heroiclands.org
• User Guide
• Rules
• Quickstart
• Character Creation