Implementation tutorials 13 min read

All extension capabilities and where to implement them

An explicit method-by-method map to projects, local helpers, surfaces, server integrations and release limits.

How to use this map

This index crosses public contracts from host 0.3.1, revision 0e91fef, with implementation projects. It covers 139 domain API methods, 17 original SDK operations, 13 surfaces and lifecycle helpers. Each method links to runnable code, inputs and a test, rather than promising arbitrary unsupported combinations.

Begin with the outcome you want to build. Use this table to locate a specific capability. A recipe can combine create/configure/read/remove because they are parts of one feature. Actions execute on click and destructive operations are identified. Use a disposable installation/campaign.

Choose the package structure

Deliverable	Structure	Complete tutorial
Journal, sheet, cards, audio or table tool	Browser package with entry and register	First module and families below
RPG sheets, types, initiative and catalog	One system package with entry/assets/content.compendiums	Complete system
Translate your own module	Private api.i18n catalogs	Translation and events
Add an installation language	locales package without system/Django	Language package
Trusted Python routes/services	Django package, owner/Runner activation	Server integration
Distribute an approved release	Immutable ZIP, hash, signature and HTTPS catalog	Publication

There is no global module-type enum. A compendium can mean a mutable campaign pack, an installed system catalog or an operator-managed local catalog, with different rules. Mounting depends on its surface rather than your module’s label.

Every domain method

Generic methods take api.domain.method(payload,{signal,requestId}) with recipe-specific fields. Reads do not need requestId. list/get project authorized state. actors.sheet, dice.roll, table.search, chat.remove and other convenience methods use their own demonstrated signatures. JavaScript method names differ from native Python action names.

api.actors

Method	Native action	Implementation project
`actors.create`	`actor.create`	Code, inputs and test
`actors.update`	`actor.update`	Code, inputs and test
`actors.delete`	`actor.delete`	Code, inputs and test
`actors.setPermissions`	`actor.permissions`	Code, inputs and test
`actors.saveSheet`	`sheet.save`	Code, inputs and test
`actors.createFolder`	`folder.create`	Code, inputs and test
`actors.updateFolder`	`folder.update`	Code, inputs and test
`actors.deleteFolder`	`folder.delete`	Code, inputs and test
`actors.deleteAsset`	`asset.delete`	Code, inputs and test
`actors.state`	`state`	Code, inputs and test
`actors.list`	`state projection`	Code, inputs and test
`actors.get`	`state projection`	Code, inputs and test
`actors.sheet`	`sheet`	Code, inputs and test

api.tokens

Method	Native action	Implementation project
`tokens.place`	`place`	Code, inputs and test
`tokens.move`	`move`	Code, inputs and test
`tokens.remove`	`remove`	Code, inputs and test
`tokens.duplicate`	`duplicate`	Code, inputs and test
`tokens.setHidden`	`hidden`	Code, inputs and test
`tokens.setVision`	`vision`	Code, inputs and test
`tokens.configure`	`configure`	Code, inputs and test
`tokens.addCondition`	`condition-add`	Code, inputs and test
`tokens.removeCondition`	`condition-remove`	Code, inputs and test
`tokens.state`	`state`	Code, inputs and test
`tokens.list`	`state projection`	Code, inputs and test
`tokens.get`	`state projection`	Code, inputs and test

api.maps

Method	Native action	Implementation project
`maps.update`	`update`	Code, inputs and test
`maps.move`	`move`	Code, inputs and test
`maps.delete`	`delete`	Code, inputs and test
`maps.activate`	`activate`	Code, inputs and test
`maps.updateObjects`	`objects`	Code, inputs and test
`maps.createFolder`	`folder-create`	Code, inputs and test
`maps.updateFolder`	`folder-update`	Code, inputs and test
`maps.deleteFolder`	`folder-delete`	Code, inputs and test
`maps.state`	`state`	Code, inputs and test
`maps.list`	`state projection`	Code, inputs and test
`maps.get`	`state projection`	Code, inputs and test
`maps.layers`	`layers`	Code, inputs and test

api.journals

Method	Native action	Implementation project
`journals.create`	`create`	Code, inputs and test
`journals.update`	`update`	Code, inputs and test
`journals.delete`	`delete`	Code, inputs and test
`journals.move`	`move`	Code, inputs and test
`journals.setAccess`	`access`	Code, inputs and test
`journals.present`	`present`	Code, inputs and test
`journals.createFolder`	`folder-create`	Code, inputs and test
`journals.updateFolder`	`folder-update`	Code, inputs and test
`journals.moveFolder`	`folder-move`	Code, inputs and test
`journals.deleteFolder`	`folder-delete`	Code, inputs and test
`journals.setStatus`	`status`	Code, inputs and test
`journals.setObjective`	`objective`	Code, inputs and test
`journals.assignCharacters`	`assign`	Code, inputs and test
`journals.createBoardQuest`	`board-create`	Code, inputs and test
`journals.addQuest`	`board-add`	Code, inputs and test
`journals.removeQuest`	`board-remove`	Code, inputs and test
`journals.pinQuest`	`board-pin`	Code, inputs and test
`journals.reorderQuests`	`board-reorder`	Code, inputs and test
`journals.roll`	`roll`	Code, inputs and test
`journals.reset`	`reset`	Code, inputs and test
`journals.state`	`state`	Code, inputs and test
`journals.list`	`state projection`	Code, inputs and test
`journals.get`	`state projection`	Code, inputs and test

api.items

Method	Native action	Implementation project
`items.create`	`create`	Code, inputs and test
`items.update`	`update`	Code, inputs and test
`items.delete`	`delete`	Code, inputs and test
`items.duplicate`	`duplicate`	Code, inputs and test
`items.setPermissions`	`permissions`	Code, inputs and test
`items.createFolder`	`folder-create`	Code, inputs and test
`items.updateFolder`	`folder-update`	Code, inputs and test
`items.deleteFolder`	`folder-delete`	Code, inputs and test
`items.state`	`state`	Code, inputs and test
`items.list`	`state projection`	Code, inputs and test
`items.get`	`state projection`	Code, inputs and test

api.combat

Method	Native action	Implementation project
`combat.add`	`add`	Code, inputs and test
`combat.remove`	`remove`	Code, inputs and test
`combat.configure`	`configure`	Code, inputs and test
`combat.setInitiative`	`initiative`	Code, inputs and test
`combat.rollInitiative`	`roll`	Code, inputs and test
`combat.toggle`	`toggle`	Code, inputs and test
`combat.moveUp`	`order-up`	Code, inputs and test
`combat.moveDown`	`order-down`	Code, inputs and test
`combat.setTurn`	`set-turn`	Code, inputs and test
`combat.nextRound`	`next-round`	Code, inputs and test
`combat.previousRound`	`previous-round`	Code, inputs and test
`combat.start`	`start`	Code, inputs and test
`combat.stop`	`stop`	Code, inputs and test
`combat.nextTurn`	`next`	Code, inputs and test
`combat.previousTurn`	`previous`	Code, inputs and test
`combat.state`	`state`	Code, inputs and test

api.cards

Method	Native action	Implementation project
`cards.define`	`define`	Code, inputs and test
`cards.instantiate`	`instantiate`	Code, inputs and test
`cards.create`	`create`	Code, inputs and test
`cards.draw`	`draw`	Code, inputs and test
`cards.shuffle`	`shuffle`	Code, inputs and test
`cards.reset`	`reset`	Code, inputs and test
`cards.deleteDeck`	`delete-deck`	Code, inputs and test
`cards.discard`	`discard`	Code, inputs and test
`cards.return`	`return`	Code, inputs and test
`cards.give`	`give`	Code, inputs and test
`cards.place`	`place`	Code, inputs and test
`cards.take`	`take`	Code, inputs and test
`cards.flip`	`flip`	Code, inputs and test
`cards.move`	`move`	Code, inputs and test
`cards.state`	`state`	Code, inputs and test

api.audio

Method	Native action	Implementation project
`audio.updateTrack`	`track-update`	Code, inputs and test
`audio.deleteTrack`	`track-delete`	Code, inputs and test
`audio.createPlaylist`	`playlist-create`	Code, inputs and test
`audio.updatePlaylist`	`playlist-update`	Code, inputs and test
`audio.deletePlaylist`	`playlist-delete`	Code, inputs and test
`audio.createSpatialSound`	`spatial-create`	Code, inputs and test
`audio.updateSpatialSound`	`spatial-update`	Code, inputs and test
`audio.deleteSpatialSound`	`spatial-delete`	Code, inputs and test
`audio.play`	`play`	Code, inputs and test
`audio.pause`	`pause`	Code, inputs and test
`audio.stop`	`stop`	Code, inputs and test
`audio.seek`	`seek`	Code, inputs and test
`audio.setVolume`	`volume`	Code, inputs and test
`audio.startScore`	`score-start`	Code, inputs and test
`audio.pauseScore`	`score-pause`	Code, inputs and test
`audio.resumeScore`	`score-resume`	Code, inputs and test
`audio.stopScore`	`score-stop`	Code, inputs and test
`audio.nextScore`	`score-next`	Code, inputs and test
`audio.previousScore`	`score-previous`	Code, inputs and test
`audio.state`	`state`	Code, inputs and test

api.compendiums

Method	Native action	Implementation project
`compendiums.create`	`create`	Code, inputs and test
`compendiums.configure`	`configure`	Code, inputs and test
`compendiums.read`	`read`	Code, inputs and test
`compendiums.delete`	`delete`	Code, inputs and test
`compendiums.add`	`add`	Code, inputs and test
`compendiums.remove`	`remove`	Code, inputs and test
`compendiums.import`	`import`	Code, inputs and test
`compendiums.setPermissions`	`permissions`	Code, inputs and test
`compendiums.state`	`state`	Code, inputs and test

api.chat

Method	Native action	Implementation project
`chat.history`	`history`	Code, inputs and test
`chat.send`	`send`	Code, inputs and test
`chat.remove`	`remove`	Code, inputs and test
`chat.clear`	`clear`	Code, inputs and test

api.dice

Method	Native action	Implementation project
`dice.roll`	`roll`	Code, inputs and test

api.table

Method	Native action	Implementation project
`table.search`	`search`	Code, inputs and test
`table.lobby`	`lobby`	Code, inputs and test
`table.updateLobby`	`updateLobby`	Code, inputs and test

Every original SDK operation

Use host.call(name,payload,{signal,onProgress}) with its corresponding contract. File/Blob must be real objects rather than JSON or local paths. Original DTOs/expectedRevision differ from domain version/sheetVersion; the linked projects demonstrate that difference.

Original operation	Transport/effect	Project
`actor.list`	json / read	Complete implementation
`actor.read`	json / read	Complete implementation
`actor.create`	json / write	Complete implementation
`actor.update`	json / write	Complete implementation
`actor.data.read`	json / read	Complete implementation
`actor.data.update`	json / write	Complete implementation
`actor.delete`	json / write	Complete implementation
`token.read`	json / read	Complete implementation
`token.move`	json / write	Complete implementation
`token.data.read`	json / read	Complete implementation
`token.data.update`	json / write	Complete implementation
`asset.list`	json / read	Complete implementation
`asset.upload`	multipart / write	Complete implementation
`asset.download`	binary / read	Complete implementation
`actor.image.upload`	multipart / write	Complete implementation
`card.asset.upload`	multipart / write	Complete implementation
`locale.apply`	json / local	Complete implementation

Every mounting surface

augment adds controls to native UI. replace owns the complete surface body and its navigation/actions. The complete system demonstrates functional actor/token sheet replacement; an existing-sheet action uses augment. Each surface below has complete source files.

Surface	Accepted modes	Complete example
`actor.directory`	`augment`, `replace`	`actor.directory`
`actor.sheet`	`augment`, `replace`	`actor.sheet`
`token.sheet`	`augment`, `replace`	`token.sheet`
`item.directory`	`augment`, `replace`	`item.directory`
`item.sheet`	`augment`, `replace`	`item.sheet`
`scene.directory`	`augment`, `replace`	`scene.directory`
`scene.controls`	`augment`, `replace`	`scene.controls`
`scene.overlay`	`augment`, `replace`	`scene.overlay`
`chat.log`	`augment`, `replace`	`chat.log`
`combat.tracker`	`augment`, `replace`	`combat.tracker`
`journal.sheet`	`augment`, `replace`	`journal.sheet`
`preferences`	`augment`, `replace`	`preferences`
`table.interface`	`augment`, `replace`	`table.interface`

Local helpers and lifecycle

Capability	Concrete API	Project to adapt
Package files	assets.url / text / json / bytes	Translation and assets
Stylesheet lifetime	styles.use and disposer	First module
Browser settings	storage.local.get / set / delete	Persistence
Account/table settings	storage.user.get / set / delete / list	Persistence
GM-shared settings	storage.table.get / set / delete / list	Persistence
Settings UI	customize(context) and preferences	Complete form
Private catalogs	api.i18n.locale / t / has / number / register / onChange	Translation
Native modal/closing	api.ui.openModal; close / suspend / resume; gravewright:sheet-flush	Customize and modals
Component registration	register, also exposed as UI registration during the register phase	First module
Authorized changes	api.events.on and unsubscribe	Events
Legacy actor hints	events.on actor.created / actor.updated / actor.deleted	Contract and limits
Coordinates/pan/zoom	viewport.sceneToViewport / viewportToScene; scene.viewport.changed	Working overlay
Cancellation/disposal	signal and onDispose per mount; start / register / stop	First module

Domain events include actors.changed, tokens.changed, maps.changed, maps.layersChanged, journals.changed, items.changed, combat.changed, cards.changed, audio.changed, compendiums.changed, chat.changed, chat.message, table.presence and table.lobbyChanged. They may coalesce invalidations and perform initial/reconnect reads. They are not exactly-once automation triggers. Dispose each subscription.

Map Builder and visual automation

All four door/lever/torch/region owners, execution/data connections and 44 node.type values have complete graphs, JSON and editor steps. The node catalog explains targets, resources and effects. Use native Test behavior/playtest before live application. These graphs are development documents, not a browser API for importing arbitrary JSON or a new manifest field.

The scene tutorial implements public layer/object operations. Adding new kinds or editor ports requires a core contribution and tests; 0.3.1 does not promise a plugin API for arbitrary node-type registration.

Server integrations and release boundaries

The Django integration implements Context.from_request, public commands, authenticated/CSRF routes and after-commit hooks. Python facades api.actors/tokens/maps/journals/items/combat/cards/audio/compendiums/resources/chat/dice/table/events have signatures in the reference. Context retains IDs rather than cached authority, and each service checks access. Account/admin/package/campaign management are global application adapters rather than methods on a mount’s api; see adapter reference for operator tools.

There is no maps.create or audio.upload domain SDK method: tutorials prepare scenes/files through native UI and then use supported public operations. Browser modules do not receive arbitrary SQL/Python execution, implicit GM powers, campaign switching through foreign UUIDs or hidden-data bypasses. system.combat supports declarative initiative. Existing Python providers are trusted server code, not permission to distribute a new RPG as a system plus separate Server Rules companion. Explain unsupported requirements while preserving the requested host version.

Maintain coverage when the host changes

This map uses a versioned frontend.json/registry.json snapshot in extension-contracts.json. For a host upgrade, compare actual source files/revisions, update projects and run their recipes against real services. Matching names alone does not prove payload, permission, visual or transaction behavior. Repeat mutation/snapshot tests in new fixtures.