# Extension API

`api: 1`

You extend DivineVTT with **packages**. A package is a folder with a `pack.json`
manifest, a set of facet files, and optionally a script. There are two roles,
and they share one format:

- A **system** is the base ruleset a world runs on: character sheets, conditions,
  the calendar, dice, initiative, token vitals, money, what a hidden thing takes
  to notice. A world has exactly one.
- A **module** adds things on top of a system: new sheet sections, automation, chat
  cards, granted items, content, a theme. A world can enable several, and a
  campaign can override the set for its own table.

Most packages use one or both of these paths:

- **Declarative facets**: JSON files describing sheets, conditions, calendars,
  dice, vitals, catalogs and twenty other kinds. This is the main path. It needs
  no code, it is editable in [Studio](https://divinevtt.com/docs/guides/studio), and it works
  everywhere, including the hosted service.
- **A script**: an ES module that registers behavior through the `api` object. Use
  it for formula functions, custom sheet nodes, panels, action sources, effects,
  and reacting to what happens at the table. Scripts from anyone but the first
  party run in a [sandbox](https://divinevtt.com/docs/guides/sandbox) with the permissions the manifest
  declares.

Everything documented here is stable. Anything not documented is internal and can
change. Within a major version the API only grows: fields and methods get added,
never removed or repurposed, so a package built for `api: 1` keeps working as the
app changes.

## Start here

- [Your first module](https://divinevtt.com/docs/getting-started): two files, a formula function,
  a setting, a hook.
- [Studio](https://divinevtt.com/docs/guides/studio): build either role in the app, with a live
  preview, lint, and a sandboxed test harness.
- [Building a system](https://divinevtt.com/docs/guides/systems): what a system is made of and the
  smallest one that plays.
- [Packages & the pack chain](https://divinevtt.com/docs/guides/packages): the manifest, every facet
  kind, and how a world resolves content across its system and modules.

## Then, by what you are making

- [Authoring character sheets](https://divinevtt.com/docs/guides/character-sheets): the node
  vocabulary that builds a sheet, no code required.
- [Rules facets](https://divinevtt.com/docs/guides/rules): conditions, dice, turn order, vitals,
  measurement, detection, skills, tracked pools, money, realism and the wound
  table, weapon properties, region switches, sounds, calendar, GM screen, theme,
  star charts.
- [Shipping content](https://divinevtt.com/docs/guides/content): catalogs, overrides, books, drop
  tables, loot tables.
- [Scripting with the api](https://divinevtt.com/docs/guides/scripting), [Effects](https://divinevtt.com/docs/guides/effects),
  [Automation patterns](https://divinevtt.com/docs/guides/automation), and
  [Permissions and the sandbox](https://divinevtt.com/docs/guides/sandbox).

## How content resolves

A world resolves content through a **pack chain**: the system first, then the
enabled modules in the GM's order. Each facet kind merges its own way. A later
`characterSheet` replaces an earlier one for the same entity kind, `conditions`
union by id, `bindings` shallow-merge, `currency` is taken whole from the last
pack that declares one, and so on. The
[Packages guide](https://divinevtt.com/docs/guides/packages#facets) has the full table, and
[Facet schemas](https://divinevtt.com/docs/reference/facets) lists every field of every kind.