Skip to main content
Both styles work. The default export is the namespace.
Points marked 2.1, 2.2, 2.3 or 2.4 were added in that SDK version. An expansion that uses any of them declares at least that version, for example "sdkVersion": "^2.1.0". Everything else exists since 2.0.0 and is unchanged.A comment like // project:read names the permission a call needs. Without it, the call throws SdkPermissionError (async calls reject with it) and the refusal is logged.

Conventions

Ids. Ids you choose are local to your expansion. pages.register('home', …) registers my_expansion.home, so two expansions can both have a home page. The qualified id is what the call returns, and what appears in routes. Local ids are letters, digits, _ and -. Some ids are not prefixed, because they are written into project files or typed by users, and are therefore app-wide: item type ids, export and import format ids, scripting target ids, CLI command names, icon names. Catalog keys for the Skills editor, GUI logic and Mechanics are prefixed, as <expansionId>_<key>, with any character of your id that is not a letter or digit replaced by _. Tool names are prefixed as <expansionId>__<name>. Dispose. Many calls return a Dispose: a function that removes what the call added. Everything you register is removed automatically on reload, disable and uninstall, so you only call it to remove something early. Project ids. projectId parameters default to the project open in the window. A call that needs a project and finds none throws No project is open; pass a projectId.

About

pages

Registers a page. Open it with a sidebar button or useNavigate().page(id). It renders at /project/<projectId>/custom/<expansionId>.<pageId>.
Adds a button to the project sidebar that opens one of your pages.
  • page is a page id you passed to pages.register.
  • icon is a Lucide icon name such as 'Star', or an image URL. Defaults to a puzzle piece.
  • label defaults to your expansion’s name.
  • 2.1 position is 'main' (default) or 'bottom'.
  • 2.1 order sorts expansion buttons; the default is 100.
  • 2.1 badge is a number or short text on the icon’s corner (the first 4 characters are shown). null or omitted shows none. setBadge changes it later and accepts a local or full button id.
Users can reorder or hide it like any built-in button. There is no sidebar outside a project, and buttons cannot be grouped.

injections

Renders a component inside an existing app screen. The component receives injectionContext, injectionMetadata, slotId and expansionId. Lower order renders first; the default is 100. A slot with nothing injected renders nothing. slots() lists every slot id. Inside the item editor, useItem() gives you the item and a setter. There are no slots in app settings or the project home; use settings.appTab and browser:header:after instead.

editors

A full editor for a kind of item, and the mapping that makes items of elementType open in it. The component receives itemId, itemData, content, setContent and readItems.

creators

register adds an entry to the Create menu that renders your component. metadata may carry label, icon, description, compatibility and category. 2.1 compatibility(creatorType, plugins) sets which plugin formats a creator type is offered for. creatorType is a built-in key such as 'create_food', or one of yours. By default the list is merged with the existing one; { merge: false } replaces it. The previous list is restored on unload. 2.1 addType(typeId, config) adds a creator that runs the app’s own staged Create flow, listed in the Add element menu next to the built-in creators. It returns the creator key create_<expansionId>_<typeId>. A stage is { stage?, type, conditions?, … }:
  • type names a built-in stage (identity, assets, assetswithtemplates, assetspngonly, blockproperties, bbmodel, cropstages, gui, mechanic, EntitySelection, ModelTypeSelection) or one of your stages added with addStage, by its local id.
  • conditions are the built-in completion checks, for example ['itemId', 'itemName'] or ['hasPngFile'].
2.1 addStage(stageId, Component) registers a stage component for addType. It receives the same props the Creator gives built-in stages. Returns the full id.

items

registerType registers a new item type for the browser. Type ids are written into project files, so they are not prefixed with your expansion id, and registering one that already exists is refused. config.editor names one of your editors; displayName, svgIcon and tabIcon control how items appear. 2.1 typeStates({ glyph: false, entity: true }) turns item types on or off in the browser. The previous states are restored on unload.

settings

appTab and projectTab add a tab to app or project settings. A section is { id, title, description?, icon?, yamlKey?, elements }. elements are the settings elements of that page (for example text, checkbox, dropdown, slider, static-text; project settings also have number, color, radio, tags, toggle-group, …), or a type you registered with elementType. Element ids are namespaced automatically as <expansionId>__<elementId>. 2.1 Reading and writing your settings:
  • get, set and onChange address your app settings by the element’s local id. onChange fires when the value changes, whether from the Settings page or from set. In a component, useSetting does the same.
  • Project settings are saved in the project’s config.yml, in the section named by the tab’s yamlKey (default configs). project(key) reads the value from whichever section holds it; setProject(key, value, { section }) writes it (section defaults to 'configs').
  • app(key) reads one of the app’s own settings, read-only: theme, fontSize, editorFontSize, debug, sounds, autoSave or notifications. Any other key throws settings.app cannot read "x".
  • elementType(typeName, Component, target) registers a custom input. The component receives { element, value, onChange(id, value) }. target is 'app', 'project' or 'both' (default). Use it in your sections as type: '<typeName>'. Returns the full type <expansionId>.<typeName>.

theme

setVariables forces CSS variables on the app. addStyle adds a stylesheet that is not scoped to your expansion, for when you deliberately want to restyle the app. Both are undone when your expansion unloads. For styling your own UI, import a CSS file instead: it is scoped for you. When a stylesheet is added or removed, the app has the code editors measure their font again, so a theme that changes the font keeps Monaco’s cursor in the right place. 2.1 register adds a theme the user can pick in Settings › Display › Theme, next to Dark, Light and Auto. base ('dark' by default, or 'light') sets the app’s data-theme; variables are applied to :root while the theme is selected, and removed when another is picked. Returns the full id. If the user selected your theme and your expansion has not loaded yet, the app shows the theme’s base until you register it. The first time the app ever sees a theme, which is when its expansion is installed, it selects it as if the user had picked it, and theme:change fires. After that the user’s choice stands: switching back to Dark is not undone on the next start. Variables only reach what the app styles through them. For anything else, such as fonts, outlines or icons, add a stylesheet while your theme is the selected one:
2.1 current() returns 'dark', 'light', 'auto' or a registered theme’s full id.

i18n

addLanguage registers a whole UI language, for example { local: 'es', label: 'Español', translations: { … } }.
Fixed in 2.1: translations are now spread into the language object as the app expects. In 2.0 they were nested and not found.
2.1 add(local, keys) adds keys to an existing language, or overrides them. '*' applies to every language. Nested objects merge, and later overlays win. 2.1 For your own UI text:
strings merges across calls. t returns the string in the user’s language, then English, then the key itself, with {name} placeholders filled from params. language() returns the user’s language code. In components, use useT, which re-renders when the language changes.

icons

New in 2.1.
source is SVG markup or an image data URL. The icon works anywhere the app takes an icon name: item types, the sidebar, modules, and so on. Names are app-wide. Registering a name that already exists (a Lucide icon or another registered icon) throws unless you pass { replace: true }; the previous icon is restored on unload.

notify

notify shows a toast and returns its id. Options:
  • type: info (default), success, warning or error
  • duration in ms (default 4000), or autoClose: false to keep it until dismissed
  • action: { label, onClick }
  • 2.1 actions: [{ label, onClick }, …] for several buttons
  • 2.1 progress: 0–100, or null for an indeterminate bar
2.1 notify.progress(message) shows a persistent toast with an indeterminate bar and returns { id, update, done, fail, dismiss }:
done(text = 'Done', type = 'success') and fail(text = 'Failed') turn it into a normal toast.

dialog

New in 2.1.
Dialogs use the app’s own dialog shell. Any dialog still open when your expansion unloads is closed and resolves null.
  • confirm takes a string (confirm('Sure?')) or { title, subtitle, message, confirmLabel, cancelLabel, danger }.
  • prompt takes { title, subtitle, message, fields, confirmLabel, cancelLabel }. It resolves { [id]: value }, or null when cancelled. Confirm stays disabled while a required field is empty. A field is:
  • open(Component, { title, subtitle, size, props, cancelLabel }) shows your own component. size is 'default' or 'wide'. The component receives props and close(value); the promise resolves that value, or null if the dialog was closed.
  • pickItem({ types?, multiple?, projectId?, title? }) shows a searchable list of the project’s items, filtered by type or subtype. Single mode resolves the clicked item record; multiple mode resolves an array on confirm. null when cancelled. The records are the ones project.items() returns. For vanilla items, use VanillaItemPicker instead.
  • pickFile({ extensions?, multiple?, encoding?, title? }) opens the native open dialog. It resolves [{ name, size, data }]: text, or a Uint8Array with encoding: 'binary'. It resolves [] when cancelled. Files over 64 MB are refused.
  • saveFile({ name?, data, extensions?, title? }) opens the native save dialog. data is text, bytes, or an object (written as JSON). Resolves { saved, name }.
  • shell.openExternal(url) opens an http: or https: URL in the user’s browser. Other schemes are refused.

commands

New in 2.1.
A command is a named action that toolbar buttons, menu entries and keybindings can point at. register returns the full id. execute accepts a local id (one of yours) or a full id (any expansion’s).

keybindings

New in 2.1.
  • key joins modifiers and one key with +. Modifiers: Ctrl, Shift, Alt (or Option), Meta (or Cmd), and Mod (Ctrl on Windows and Linux, Cmd on macOS). Keys: K, F2, Esc, Space, Up, and so on. A combo with no key throws.
  • Give either command (a local or full id) or run(context). context is { projectId, route, inInput }.
  • when(context) returning false skips the binding.
  • While focus is in a text field (inputs, textareas, Monaco), a binding is ignored unless it has inInput: true.
Bindings are app-wide. The app has no keybinding settings screen, so they are not listed in the UI; document yours.

cli

New in 2.1.
Adds a command to the app’s CLI (the footer console). Echo can run these too. run(ctx) receives { args, flags, raw, rest, app, print(text, type), clear() } and returns a line, an array of lines, or nothing. A thrown message is shown as an error line. group: 'write' marks a command that changes something, so Echo asks the user before running it. Names are app-wide; registering an existing name replaces it until your expansion unloads. cli.run(line) runs a line as if typed in the console.

Example: one command, four ways in

contextMenu

New in 2.1.
An unknown target throws. Your entries appear after the built-in ones, below a separator, sorted by order (default 100). danger: true styles the entry as destructive. A run that fails shows an error toast.

toolbar

New in 2.1.
Give either command or run. The button shows its icon, or the label when there is no icon; tooltip defaults to label.

statusBar

New in 2.1.
A status item in the window’s footer: an icon and text, clickable when it has command or run. Pass component instead for a fully custom item (rendered with no props). update changes text, tooltip or icon in place. Returns the full id.

panels

New in 2.1.
Side panels in the project window. A rail of icon buttons sits on the right edge; clicking one opens its panel, 320 px wide, beside the workspace. One panel is open at a time. The component receives context: { projectId }. open, close and toggle accept local or full ids.

routes

New in 2.1.
A full page outside any project, at #/x/<expansionId>.<routeId>. Open it with useNavigate().route(routeId). An unknown route, or one whose expansion has not loaded yet, shows a message.

home

New in 2.1.
A card on the projects window, above the project board.

addElementMenu

New in 2.1.
An entry in the project browser’s Add element menu, grouped by category (default 'expansion'). Instead of opening a creator it runs run({ projectId, folder, projectFormat }). For an entry that runs the app’s Create flow, use creators.addType.

apps

New in 2.2.
An app is a tool that stands on its own, outside any project, on a page of its own at #/app/<expansionId>.<id>. Opening one shows its icon at the centre of the window while it loads, then the app. The projects window’s app dock shows the apps used most recently, as many as fit one row. Its All button, or Ctrl+K anywhere, opens the launcher: every app, the last used on top, then by category, searchable.
  • icon is a Lucide icon name ("Hammer") drawn on a tile of accent (any CSS colour; the app’s own colour by default), or an image URL that fills the tile. Without one, or when the image fails to load, the dock draws a placeholder.
  • component gets the page below a header with a way back, your icon and name, and receives { close, args }. close() goes back to where the app was opened from. args is whatever open was given; null from the dock, the launcher, or back and forward.
  • category groups it in the launcher: create, server, utilities, learn, or a word of your own. Without one it is other.
  • order sorts the dock; the built-in apps are 0, and yours default to 100.
  • An app is removed with your expansion. If it was open, its page says it is no longer there and offers the way back.
An expansion that is mainly an app says so in meta.json with "type": "app". See Manifest.

tools

New in 2.3.
A tool is an action AI assistants can take, typed the way model tool-calling expects. Echo uses them, and so do assistants the user connects over MCP (Claude Desktop, Claude Code, Cursor) when App Settings › AI › Let AI assistants use Lode Studio is on. Every AI sees the same list, Lode Studio’s own tools first.
  • name: lowercase a-z, 0-9 and _, at most 48 characters. It is registered as <expansionId>__<name>, which register returns, so two expansions never collide. The full name must fit in 64 characters.
  • description: what it does and when to use it. This is all the AI has to go on, so write it for a reader who has never seen your expansion. Required.
  • input: JSON Schema, { type: 'object', properties, required }. Calls are checked against it before run, and a wrong call comes back to the AI saying what was wrong.
  • run(input): return text, or anything JSON can carry. Throw with a sentence the AI can act on (“No palette called Warm. list_palettes shows what exists.”).
  • readOnly: true for a tool that only reads. Anything else is a write: the user is asked in Lode Studio before it runs, unless they turned on Bypass permissions, and a declined call tells the AI not to retry. destructive: true marks one that cannot be undone, and the question says so.
Tools go with your expansion when it reloads, is disabled or is uninstalled.

project

Reads need project:read; changes need project:write.
  • current() is the open project’s id, or null outside a project.
  • Addressing an item. Where a call takes item, pass a path below Data (tools/ruby_sword), the full Projects/<id>/Data/... path, or { path }, { id } (the item id) or { uid } (the immutable id).
  • Item records. items(), query() and dialog.pickItem() return { namespace, type, subtype, uid, nodeKey, path, data, pack, modifiedAt }. data is the item.yml content, nodeKey the path below Data, and pack its assets.
  • 2.1 query matches every field you give. folder is the item’s folder below Data ('' for the root); where(item) is any further test.
  • 2.1 getItem returns the item’s full read: item.yml content, meta and assets.
  • updateItem({ path, changes }) applies changes to the item YAML at path.
  • 2.1 createItem goes through the explorer’s own channel. The id is checked (/^[a-z0-9_\-./]+$/, unique project-wide), a uid is assigned, and the browser refreshes. type defaults to 'item'; folder is below Data (omit it for the root); data adds item.yml fields. Resolves { path, data }.
  • 2.1 renameItem, duplicateItem, moveItem and deleteItem use the browser’s own operations, and the browser refreshes. moveItem’s folder is below Data ('' for the root).
  • 2.1 info() returns { id, name, format, version, author, plugins, family, cloud, config }, where family is 'java' or 'bedrock' and config is the whole config.yml.
  • 2.1 list() returns [{ id, name, format, version, cloud }] for every project.
  • 2.1 watch(handler) calls handler([{ type: 'change' | 'rename', path }]) with changes batched over about 150 ms, anywhere in the project folder and from any source: editors, syncs, teammates, outside programs. path narrows it to a sub-folder. The app’s temporary export folders are ignored.
  • 2.1 settings.get and settings.set read and write keys of the configs section of config.yml, as the Project Settings page does.
These changes fire app events such as item:create and item:save.

Project files

  • Paths are relative to the project folder. Subfolders are created as needed, and any path that escapes the project is refused.
  • readFile returns data (the text) and parsed (the value, for .json, .yml and .yaml). 2.1 With encoding: 'binary', data is a Uint8Array.
  • writeFile takes text or an object (written as JSON or YAML by the app). 2.1 It also takes a Uint8Array or ArrayBuffer.
  • 2.1 listFiles returns { path, type: 'file' | 'directory', size? } entries, with paths relative to the project.
  • 2.1 deleteFile removes a file or folder, but never the project folder itself.

projects

New in 2.4.
Settings > General > Project type shows a project’s template (its content plugin) and its features: entities, scripting, guis and geyser. A feature that is off hides its creators and its items, and leaves them out of every export; its files stay.
  • addTemplate names your content format there. format is your content exporter’s id, and defaults is what a new project of this template starts with, for example defaults: { entities: 'nmentities', scripting: 'denizen', guis: true }. Without a template, your format still shows, under its own name.
  • addChoice offers your plugin under a feature. sets may only write entityModelExporter, entityBehaviorExporter and scriptingExporter. Any other feature id throws Unknown feature.
  • A scripting target is offered under Scripting without a choice of its own.
  • Whether a feature is offered at all follows its creators’ compatibility (sdk.creators.compatibility).

assets, textures, models, audio

New in 2.1.
  • assets.add writes into the item’s own assets folder and adds the file to the item’s asset list. kind is 'textures', 'models' or 'sounds'. data is bytes or base64 for textures and sounds, and an object or JSON text for models. remove deletes one; list returns the item’s assets. There is no project-wide asset store.
  • textures.load(path) returns a blob URL an <img> can show. It is revoked on unload.
  • models.load(path) returns { json } for .json and .bbmodel files, and { url } for others.
  • blockbench.open(path) opens a project model in Blockbench, using the user’s configured path or the auto-detected one.
  • audio.play(src) plays an imported sound URL (no permission) or a project file path (project:read). volume is 0–1. Audio still playing stops on unload.

storage

New in 2.1. Needs no permission.
  • storage and storage.project(id) hold small JSON values. They are the same stores useGlobalState and useProjectState use, so a value set here is what the hook reads on its next mount.
  • storage.files is a private folder in the app’s user data, for larger data. Nobody else can read it, paths cannot escape it, and it is deleted when your expansion is uninstalled.

clipboard

yaml

New in 2.1.

net

New in 2.1.
Fetches a URL into the project folder as bytes, and the browser refreshes. Downloads over 256 MB are refused. For anything else, use fetch or WebSocket (both need network).

minecraft

New in 2.1.
  • itemList is the vanilla list the app’s pickers use. It is cached when no version is given.
  • sounds() returns sound event ids such as entity.zombie.ambient; { bukkit: true } returns Bukkit enum names.
  • hardness gives the reference values the block editor uses, and the label for a value. There is no per-block hardness table.

text

New in 2.1.
MiniMessage tags are the app’s canonical display-text format. fromLegacy converts & and § codes to tags, and toLegacy does the reverse. strip removes formatting. parse returns styled segments: [{ text, color, gradient, bold, italic, underlined, strikethrough, obfuscated }].

export

New in 2.1.
Exports run in the app, outside the window. Your functions run in the window and are called when an export reaches them. They may be async, but should not take minutes: exporters and transforms time out after 10 minutes. A function that throws is logged against your expansion and skipped, and the export continues.

Exporters

id is lowercase letters, digits, _ and -, and is app-wide. category is content (default), entityModels, entityBehavior or scripting; the exporter appears under it in the export modal.
  • A content exporter is also a format a project can export and sync to. Its output goes to the plugin folder folder (default: the name). registerFormat is registerExporter with category: 'content'.
  • Exporters in the other categories run in production packs, into their own folder of the pack.
run({ items, projectId, pluginName, mainPlugin }) receives the project’s items and returns the files to write, in any of these shapes:
  • [{ path, content }]: content is text, or an object written as YAML (or JSON if the path ends in .json)
  • [{ path, data }]: data is a Uint8Array
  • { 'path/file.yml': content, … }
  • { files, warnings?, errors? }, with any of the above as files. Warnings are logged; errors fail the export with those messages.
Paths are relative to the exporter’s output folder, and a path that escapes it is refused.

Changing other exports

  • transform(format, fn) runs before the format’s exporter, once per item. Return the (changed) item, or null to leave it out of this export. format is a format id, or '*' for every format.
  • transformFile(format, glob, fn) runs after the exporter, for each output file whose path (relative to the output folder) matches glob. content is the text and parsed the YAML or JSON value when it parses. Return a string, an object (written back as YAML, or JSON for .json), or nothing to leave the file alone.
  • addFiles(format, fn) runs after the exporter and returns extra files, in the exporter’s file shapes.
Item transforms see items, not output; rewrite output with transformFile or modules.export. Transforms, file transforms and extra files also run for the Coder’s previews, which run the real exporter, so what the Coder shows is what ships. Globs (also used by coder.addLinter) are /-separated, case-insensitive, and matched against the whole path. * matches within one segment; ** matches zero or more segments.

Running and listing

run(format) starts a production export of the project to format, as the export modal does, using the project’s version unless you pass one. formats() lists every exportable format (built-in, legacy and SDK); exporters() lists exporters by category.

import

New in 2.1.

Importers

An importer is offered when the user imports a plugin pack (a zip) as a new project, alongside the built-in Nexo, ItemsAdder and CraftEngine importers. id is the format id, lowercase.
  • detect({ files, folderName }) is called for each folder of the extracted zip, shallowest first, with up to 2000 file paths relative to that folder. Return true if the folder is yours.
  • run({ files, read, projectId }) is called with every file path of the detected folder. read(path, { encoding: 'utf8' | 'binary' }) reads a source file while the import runs. Return { items, warnings?, errors? }.
Each item is { id, folder?, namespace?, type?, data?, sourceId?, assets? }, where assets is [{ from, kind: 'textures' | 'models', name? }]. The app writes Data/<folder>/<namespace>/<id>/item.yml with data, id and type (default item). folder defaults to imported, namespace defaults to the folder, and ids are sanitised. Assets are copied: model texture references are rewritten to point at the copied textures, and .mcmeta files come along. An import that produces no items and has errors fails, and the new project is removed.

Import transforms

transform(format, fn) runs after a built-in importer wrote its items. fn receives each item’s item.yml content and a summary, { itemId, sourceId, folder, namespace, type, assetsCopied }. Return new content to write it back. format is the importer id or '*'.

Drop handlers

Files dropped on the project browser whose names end in one of extensions (with or without the dot) go to handle({ files: [{ name, size, data: Uint8Array }], projectId, folder }), and the browser refreshes afterwards. Files no handler claims go to the app’s own drop handling (.nxn, .nxi, .bbmodel, …).

modules

register({ name, display, description, icon, category, plugins, type, default, component, … }) adds a module to the item editor’s module picker. With component, your component renders it; without, type selects a built-in input. Returns name. 2.1 register also takes:
  • visibleWhen({ type, subtype, format, modules }): the module is offered in the picker only when this returns true. modules is the item’s { moduleName: value }. A predicate that throws shows the module.
  • export: the same as modules.export(name, …).
  • validate: the same as modules.validate(name, …).
2.1 override(name, patch) changes a module defined by the app or another expansion. hidden: true keeps it out of the add-module picker (items that already have it keep their value). You can also patch display, description, icon, category, plugins, compatibility and other definition fields. Overrides apply after legacy overrides, in registration order. 2.1 registerCategory adds a category to the add-module picker. icon is a Lucide name or a component. An existing id throws. 2.1 validate(name, fn): fn(value, item) returns a warning string, an array of them, or nothing. Warnings show above the item’s modules, are re-checked as the user edits, and are logged when the item is exported. 2.1 export(name, fns) decides what the module writes into exported plugin configs. For each item that has the module, the function for the export’s format (or '*') returns keys that are deep-merged into the item’s entry in the Nexo, ItemsAdder and CraftEngine output, winning over the exporter’s own keys. For any other format, the keys are available to its exporter on the item at yamlData._sdkExport[<format>].

blueprints and templates

New in 2.1.
  • Images (preview, textures, a skin’s path) are data URLs, http(s) URLs, or base64 PNG.
  • addSkin adds a texture variant to a piece option.
  • templates.add adds a starting model and texture for a creator type in the Create flow. texture is required.
  • Blueprint editor tools sit in its top bar and run run({ categoryId, blueprint, name, mode }). Panels render in its side column (the blueprint-editor:panel slot).

Logic editors

New in 2.1.
Entries are plain data, with no functions: the editors’ previews (in the window) and the export (outside it) compile the same text from the same data. Where a catalog would need a function, the entry gives a template string instead, with {field} placeholders. {{ and }} are literal braces, and unknown names render empty. A plugin an entry has no spelling for is left out of that plugin’s output, with a warning. Built-in keys can never be replaced.

Skills editor

Output for MythicMobs and Lode Entities. Lode Entities’ spelling is keyed nmentities, the id it kept when it was renamed from NMEntities. Keys are prefixed: addMechanic('shout', …) registers <expansionId>_shout and returns it.
  • Mechanic: { label, group?, groupLabel?, groupIcon?, playersOnly?, fields, mythicmobs?, nmentities? }. fields are { key, label, type?, default?, … }. Each plugin spelling is { name, attrs?, quote?, fixed?, items?, drop?, spread? }: attrs maps a field key to the plugin’s attribute name, quote lists fields written quoted, and fixed adds constant attributes. A group that does not exist is created (labelled groupLabel) and removed with its last entry.
  • Trigger: { label, group?, target?, hint?, mythicmobs: '~onX', nmentities: '+onX' }. {interval} is available.
  • Targeter: { label, radius?, mythicmobs: '@X{r={radius}}', nmentities: '…' }.
  • Condition: { label, fields?, subject?, mythicmobs: 'flag{f={flag}}', nmentities: '…' }, templated over the condition’s fields.

GUI logic

Keys are prefixed like Skills keys. Each entry spells itself per scripting target in targets, keyed by target id: denizen for the built-in one. Templates get the node’s field values, plus {gui}: the GUI’s inventory script name.
  • Step: { label, group?, note?, fields?, targets: { denizen: ['- heal', '- narrate "{msg}"'] } }. A spelling is a line or an array of lines.
  • Check: { label, condition: true, fields?, targets: { denizen: '<player.has_flag[{flag}]>' } }. It has true and false outputs.
  • Trigger: { label, hint?, fields?, targets: { denizen: 'on player clicks {button} in {gui}' }, denizenHead? }, where denizenHead is a line or an array of lines.
The older top-level denizen, denizenTest and denizenEvent fields still work, and mean the same as targets.denizen.

Mechanics entries

Triggers, actions and conditions for the Mechanics node editor. Keys are prefixed, and each entry spells itself per scripting target:
  • Trigger: { label, category, categoryLabel?, categoryIcon?, targets }.
  • Action: { label, icon?, category?, params: ['message'] or [{ name, type }], targets }. A spelling may be an array of lines.
  • Condition: { label, targets }, used by If True and If False.
A target your entry has no spelling for reports it rather than guessing.
NMScript and sdk.nmscript are retired. Mechanics are built in the node editor and compiled by the project’s scripting target. Hand-written NMScript from before then still exports through Denizen.

GUI editor elements

guiEditor.addElement adds a preset of a built-in element, listed under Expansions in the Elements panel. base is 'button' (default), 'slot', 'text', 'shape' or 'image'. defaults is { name?, width?, height?, properties? }, applied over the base element. An image preset without defaults.properties.src asks the user for a file, like the built-in image element. A preset is not a new kind of element: rendering, the inspector and export are the base element’s.

scripting

Mechanics and GUIs compile through the project’s scripting target: Denizen is built in, and an expansion can add another, such as Skript. Users pick one in Project Settings › General, under Exporters. The full guide is Scripting targets.
compile(bundle, { catalog }) gets every mechanic (its trigger and nested steps) and GUI (elements, open command, title glyph, Logic program) in the project, and returns [{ path, content }]. The export, Sync, production packs, the editors’ code views, the test server’s plugin jar and its reload all follow the user’s choice. addTrigger, addAction and addCondition are under Mechanics entries.

coder

New in 2.1.
  • Formats give files matched by routes (globs over the path the Coder’s tree shows, such as Nexo/items/*.yml) a Monaco language. extends is a base language ('yaml', 'json'); highlight is Monarch rules; tokens is theme rules; suggestions is an array of completions or (ctx) => array. typeId is qualified as <expansionId>.<typeId> and returned. The app’s own formats in pages/Project/Coder/formats/ are good examples.
  • Linters run on files whose path or name matches glob, once the text settles (about 400 ms). Return [{ line, column?, endLine?, endColumn?, message, severity? }]. Lines and columns are 1-based; severity is 'error', 'warning' (default) or 'info'. Problems show as editor markers with your expansion id as the source. parsed is the YAML or JSON value when the file parses.
  • addPreview is the same as export.addFiles: the Coder’s preview runs the real exporter, so files added there also ship.

events

Listen to what the user does, or send your own event. Any number of listeners per event, including several from one expansion; each on returns its own unsubscribe, and all of them are removed when your expansion unloads. once removes itself after the first call. emit reaches every expansion, including legacy ones, so it is also how two of your own expansions talk to each other. Namespace your own events, for example my_expansion:thing-happened. For a direct API between expansions, see services.

Events the app fires

Since 2.0:
New in 2.1:

Intercepting

New in 2.1. intercept(name, (payload, { cancel, replace }) => …) runs before the action happens.
  • cancel(reason?), or returning false, stops it.
  • replace(newPayload) lets it go ahead with a changed payload.
Interceptors run in registration order and the first cancel wins. One that throws is logged and treated as having no opinion. The reason reaches the user: as a warning toast for a delete, as the error in the rename or duplicate dialog, and as the error message of a failed export, sync, import or push (code 409, or CANCELLED for a push). The first four are the user’s actions in the project browser. Changes you make through sdk.project are not intercepted.

server and sync

New in 2.1.
  • Status. status is 'stopped', 'starting', 'running', 'stopping' or 'crashed', for the server of the open project window. In components, use useServerStatus.
  • Control. send needs the server running (a leading / is optional). start, stop and sync.run press the project window’s buttons.
  • Console. onConsole receives each console line as plain text (HTML stripped, up to 4000 characters) with its level code.
  • Reload commands are added to the automatic sync script: a static commands list, and/or build({ primaryPlugin, items: [{ itemId, namespace, type }] }) returning commands. plugin limits it to projects whose main plugin is that one.
  • Sync hooks. before({ projectId, version, plugins, sync }) and after({ …, success, message }) run around every Sync, and are awaited.
  • Sync-script directives. The user’s sync script (one instruction per line: /command, -wait N, # comment) gains -<name> args… lines. When the script reaches one, fn({ name, args, plugin }) returns the console commands to send, or { commands, wait } where wait is seconds to wait afterwards (0–300). name is letters, digits, _ and -, and cannot be wait. Unregistered -name lines are skipped as before.
  • Server types are server software the user can pick in Project Settings › Server software. The tab appears while any expansion provides a type; the choice is saved as environment.serverType in config.yml, and empty means Paper. The jar is downloaded from jarUrl (with {version} replaced by the project’s Minecraft version) or from the URL resolve(version) returns, and takes Paper’s place (main.jar) the next time the server starts. Switching back to Paper downloads Paper again. The software must start like Paper (java -jar main.jar): Purpur, Folia, Pufferfish and similar.
  • SFTP hooks. beforePush({ projectId, message, files }) and afterPush({ …, success }) run around every Push environment to server. They receive the file list, never file contents.
Sync hooks and directives time out after 10 minutes; a hook that throws is logged and skipped, and the sync continues.

echo

New in 2.1.
  • Context functions are called synchronously for every question, and their lines are added to the context Echo receives. The whole context field is capped at 200 characters, so keep lines short. A function that throws is ignored for that question.
  • Tools are CLI commands Echo may run in a cli code block. write: true makes Echo ask the user before running one.
  • ask sends a question on the user’s behalf and is billed to their monthly Echo allowance. sources are [{ id, label, path }].

run

New in 2.1. Background scripts.
Runs a module, and everything it imports, in a Web Worker. The file must be listed in config.json background; otherwise the call throws sdk.run: "x" is not a file of this expansion. The .ts, .js, .tsx, .jsx and .mjs extensions may be omitted. Inside the worker, import from sdk (named or as the default export):
  • data: what was passed to run
  • send(message): posts to job.on listeners
  • on(fn): receives job.send messages
  • log.*: writes to your expansion’s log
  • isWorker: true
The module’s default export, or a run export, is called with (data, sdk). What it returns or resolves resolves job.result; a throw rejects it. There is no React, no sdk/ui, no DOM and no other sdk point inside a worker. fetch, XMLHttpRequest and WebSocket exist only with network. terminate() rejects result with Background script stopped. Running scripts are terminated on unload.

services

New in 2.1.
A service is an object of functions another expansion calls directly. It is removed when its provider unloads, and whenAvailable resolves as soon as it is (re)provided. To depend on another expansion, name it in requires so it starts first. expansions.list covers SDK expansions. status is ready, disabled, needs-approval or error.

app

New in 2.1.
user() is null when signed out. It never exposes tokens.

undo

New in 2.1.
Each expansion has its own undo stack of 100 entries. Ctrl+Z (Cmd+Z) undoes, and Ctrl+Y or Ctrl+Shift+Z redoes, while your expansion’s own UI was the last thing clicked or focused, outside text fields (they keep their native undo). Pushing clears the redo list. The app has no app-wide undo history to join; each editor keeps its own.

teamPresence

New in 2.1.
Messages reach the same expansion in teammates’ windows on the same cloud project. They never reach other expansions, and never the sender. self() is null outside a cloud project.

log

log writes to your expansion’s log, visible on the Expansions page, and to devtools. Plain console.* inside your expansion goes to the same place. For toasts, see notify.

Expansion

The optional base class for a class-based expansion, with this.sdk, onLoad and onUnload.

Errors

Thrown when a call needs a permission your meta.json does not declare, or the user has not approved. Its permission property names the missing permission.