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
useNavigate().page(id). It renders at /project/<projectId>/custom/<expansionId>.<pageId>.
sidebar
pageis a page id you passed topages.register.iconis a Lucide icon name such as'Star', or an image URL. Defaults to a puzzle piece.labeldefaults to your expansion’s name.- 2.1
positionis'main'(default) or'bottom'. - 2.1
ordersorts expansion buttons; the default is 100. - 2.1
badgeis a number or short text on the icon’s corner (the first 4 characters are shown).nullor omitted shows none.setBadgechanges it later and accepts a local or full button id.
injections
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
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?, … }:
typenames a built-in stage (identity,assets,assetswithtemplates,assetspngonly,blockproperties,bbmodel,cropstages,gui,mechanic,EntitySelection,ModelTypeSelection) or one of your stages added withaddStage, by its local id.conditionsare the built-in completion checks, for example['itemId', 'itemName']or['hasPngFile'].
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,setandonChangeaddress your app settings by the element’s local id.onChangefires when the value changes, whether from the Settings page or fromset. In a component,useSettingdoes the same.- Project settings are saved in the project’s
config.yml, in the section named by the tab’syamlKey(defaultconfigs).project(key)reads the value from whichever section holds it;setProject(key, value, { section })writes it (sectiondefaults to'configs'). app(key)reads one of the app’s own settings, read-only:theme,fontSize,editorFontSize,debug,sounds,autoSaveornotifications. Any other key throwssettings.app cannot read "x".elementType(typeName, Component, target)registers a custom input. The component receives{ element, value, onChange(id, value) }.targetis'app','project'or'both'(default). Use it in your sections astype: '<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:
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.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,warningorerrordurationin ms (default 4000), orautoClose: falseto keep it until dismissedaction: { label, onClick }- 2.1
actions: [{ label, onClick }, …]for several buttons - 2.1
progress: 0–100, ornullfor an indeterminate bar
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.null.
confirmtakes a string (confirm('Sure?')) or{ title, subtitle, message, confirmLabel, cancelLabel, danger }.prompttakes{ title, subtitle, message, fields, confirmLabel, cancelLabel }. It resolves{ [id]: value }, ornullwhen cancelled. Confirm stays disabled while a required field is empty. A field is:open(Component, { title, subtitle, size, props, cancelLabel })shows your own component.sizeis'default'or'wide'. The component receivespropsandclose(value); the promise resolves that value, ornullif the dialog was closed.pickItem({ types?, multiple?, projectId?, title? })shows a searchable list of the project’s items, filtered bytypeorsubtype. Single mode resolves the clicked item record; multiple mode resolves an array on confirm.nullwhen cancelled. The records are the onesproject.items()returns. For vanilla items, useVanillaItemPickerinstead.pickFile({ extensions?, multiple?, encoding?, title? })opens the native open dialog. It resolves[{ name, size, data }]: text, or aUint8Arraywithencoding: 'binary'. It resolves[]when cancelled. Files over 64 MB are refused.saveFile({ name?, data, extensions?, title? })opens the native save dialog.datais text, bytes, or an object (written as JSON). Resolves{ saved, name }.shell.openExternal(url)opens anhttp:orhttps:URL in the user’s browser. Other schemes are refused.
commands
New in 2.1.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.keyjoins modifiers and one key with+. Modifiers:Ctrl,Shift,Alt(orOption),Meta(orCmd), andMod(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) orrun(context).contextis{ 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.
cli
New in 2.1.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.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.context: { projectId }. open, close and toggle accept local or full ids.
routes
New in 2.1.#/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.addElementMenu
New in 2.1.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.#/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.
iconis a Lucide icon name ("Hammer") drawn on a tile ofaccent(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.componentgets the page below a header with a way back, your icon andname, and receives{ close, args }.close()goes back to where the app was opened from.argsis whateveropenwas given;nullfrom the dock, the launcher, or back and forward.categorygroups it in the launcher:create,server,utilities,learn, or a word of your own. Without one it isother.ordersorts 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.
meta.json with "type": "app". See Manifest.
tools
New in 2.3.name: lowercasea-z,0-9and_, at most 48 characters. It is registered as<expansionId>__<name>, whichregisterreturns, 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 beforerun, 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: truefor 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: truemarks one that cannot be undone, and the question says so.
project
Reads needproject: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 belowData(tools/ruby_sword), the fullProjects/<id>/Data/...path, or{ path },{ id }(the item id) or{ uid }(the immutable id). - Item records.
items(),query()anddialog.pickItem()return{ namespace, type, subtype, uid, nodeKey, path, data, pack, modifiedAt }.datais theitem.ymlcontent,nodeKeythe path below Data, andpackits assets. - 2.1
querymatches every field you give.folderis the item’s folder below Data (''for the root);where(item)is any further test. - 2.1
getItemreturns the item’s full read:item.ymlcontent, meta and assets. updateItem({ path, changes })applieschangesto the item YAML atpath.- 2.1
createItemgoes through the explorer’s own channel. The id is checked (/^[a-z0-9_\-./]+$/, unique project-wide), a uid is assigned, and the browser refreshes.typedefaults to'item';folderis below Data (omit it for the root);dataaddsitem.ymlfields. Resolves{ path, data }. - 2.1
renameItem,duplicateItem,moveItemanddeleteItemuse the browser’s own operations, and the browser refreshes.moveItem’sfolderis below Data (''for the root). - 2.1
info()returns{ id, name, format, version, author, plugins, family, cloud, config }, wherefamilyis'java'or'bedrock'andconfigis the wholeconfig.yml. - 2.1
list()returns[{ id, name, format, version, cloud }]for every project. - 2.1
watch(handler)callshandler([{ 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.pathnarrows it to a sub-folder. The app’s temporary export folders are ignored. - 2.1
settings.getandsettings.setread and write keys of theconfigssection ofconfig.yml, as the Project Settings page does.
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.
readFilereturnsdata(the text) andparsed(the value, for.json,.ymland.yaml). 2.1 Withencoding: 'binary',datais aUint8Array.writeFiletakes text or an object (written as JSON or YAML by the app). 2.1 It also takes aUint8ArrayorArrayBuffer.- 2.1
listFilesreturns{ path, type: 'file' | 'directory', size? }entries, with paths relative to the project. - 2.1
deleteFileremoves a file or folder, but never the project folder itself.
projects
New in 2.4.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.
addTemplatenames your content format there.formatis your content exporter’s id, anddefaultsis what a new project of this template starts with, for exampledefaults: { entities: 'nmentities', scripting: 'denizen', guis: true }. Without a template, your format still shows, under its own name.addChoiceoffers your plugin under a feature.setsmay only writeentityModelExporter,entityBehaviorExporterandscriptingExporter. Any other feature id throwsUnknown 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.addwrites into the item’s own assets folder and adds the file to the item’s asset list.kindis'textures','models'or'sounds'.datais bytes or base64 for textures and sounds, and an object or JSON text for models.removedeletes one;listreturns 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.jsonand.bbmodelfiles, 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).volumeis 0–1. Audio still playing stops on unload.
storage
New in 2.1. Needs no permission.storageandstorage.project(id)hold small JSON values. They are the same storesuseGlobalStateanduseProjectStateuse, so a value set here is what the hook reads on its next mount.storage.filesis 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.fetch or WebSocket (both need network).
minecraft
New in 2.1.itemListis the vanilla list the app’s pickers use. It is cached when no version is given.sounds()returns sound event ids such asentity.zombie.ambient;{ bukkit: true }returns Bukkit enum names.hardnessgives 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.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.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
contentexporter is also a format a project can export and sync to. Its output goes to the plugin folderfolder(default: the name).registerFormatisregisterExporterwithcategory: '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 }]:contentis text, or an object written as YAML (or JSON if the path ends in.json)[{ path, data }]:datais aUint8Array{ 'path/file.yml': content, … }{ files, warnings?, errors? }, with any of the above asfiles. Warnings are logged; errors fail the export with those messages.
Changing other exports
transform(format, fn)runs before the format’s exporter, once per item. Return the (changed) item, ornullto leave it out of this export.formatis 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) matchesglob.contentis the text andparsedthe 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.
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. Returntrueif 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? }.
{ 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 ofextensions (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.modulesis the item’s{ moduleName: value }. A predicate that throws shows the module.export: the same asmodules.export(name, …).validate: the same asmodules.validate(name, …).
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’spath) are data URLs,http(s)URLs, or base64 PNG. addSkinadds a texture variant to a piece option.templates.addadds a starting model and texture for a creator type in the Create flow.textureis required.- Blueprint editor tools sit in its top bar and run
run({ categoryId, blueprint, name, mode }). Panels render in its side column (theblueprint-editor:panelslot).
Logic editors
New in 2.1.{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 keyednmentities, 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? }.fieldsare{ key, label, type?, default?, … }. Each plugin spelling is{ name, attrs?, quote?, fixed?, items?, drop?, spread? }:attrsmaps a field key to the plugin’s attribute name,quotelists fields written quoted, andfixedadds constant attributes. Agroupthat does not exist is created (labelledgroupLabel) 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 intargets, 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? }, wheredenizenHeadis a line or an array of lines.
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.
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 asNexo/items/*.yml) a Monaco language.extendsis a base language ('yaml','json');highlightis Monarch rules;tokensis theme rules;suggestionsis an array of completions or(ctx) => array.typeIdis qualified as<expansionId>.<typeId>and returned. The app’s own formats inpages/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;severityis'error','warning'(default) or'info'. Problems show as editor markers with your expansion id as the source.parsedis the YAML or JSON value when the file parses. addPreviewis the same asexport.addFiles: the Coder’s preview runs the real exporter, so files added there also ship.
events
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:Intercepting
New in 2.1.intercept(name, (payload, { cancel, replace }) => …) runs before the action happens.
cancel(reason?), or returningfalse, stops it.replace(newPayload)lets it go ahead with a changed payload.
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.
statusis'stopped','starting','running','stopping'or'crashed', for the server of the open project window. In components, useuseServerStatus. - Control.
sendneeds the server running (a leading/is optional).start,stopandsync.runpress the project window’s buttons. - Console.
onConsolereceives 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
commandslist, and/orbuild({ primaryPlugin, items: [{ itemId, namespace, type }] })returning commands.pluginlimits it to projects whose main plugin is that one. - Sync hooks.
before({ projectId, version, plugins, sync })andafter({ …, 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 }wherewaitis seconds to wait afterwards (0–300).nameis letters, digits,_and-, and cannot bewait. Unregistered-namelines 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.serverTypeinconfig.yml, and empty means Paper. The jar is downloaded fromjarUrl(with{version}replaced by the project’s Minecraft version) or from the URLresolve(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 })andafterPush({ …, success })run around every Push environment to server. They receive the file list, never file contents.
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
clicode block.write: truemakes Echo ask the user before running one. asksends a question on the user’s behalf and is billed to their monthly Echo allowance.sourcesare[{ id, label, path }].
run
New in 2.1. Background scripts.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 torunsend(message): posts tojob.onlistenerson(fn): receivesjob.sendmessageslog.*: writes to your expansion’s logisWorker: true
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.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.teamPresence
New in 2.1.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
this.sdk, onLoad and onUnload.
Errors
meta.json does not declare, or the user has not approved. Its permission property names the missing permission.