> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripting targets

> Export Mechanics and GUIs to Skript, or any scripting plugin, instead of Denizen

Mechanics (the node editor) and GUIs (layout and Logic) are not written in any one scripting language. The app compiles them with the project's **scripting target**: Denizen by default, or a target an expansion registers, such as Skript. Users pick one in **Project Settings › General**, under Exporters.

```text theme={null}
Mechanics editor ─┐                                        ┌─ Denizen (built in)
GUI editor ───────┼─> script bundle (plain data) ─> target ─┼─ Skript (an expansion)
                  │                                        └─ your plugin (an expansion)
```

A target is one function from the bundle to files. Everything else follows from the user's choice: the export, Sync, production packs, the editors' code views, the test server's plugin jar and its reload command. Denizen goes through this same path: it is a target like yours, built in.

A complete target is the Skript expansion, open source at [Nexo-Maker/ls-expansion-skript](https://github.com/Nexo-Maker/ls-expansion-skript). It's built on four libraries you can reuse: `target-kit` (reading the bundle, for a target in any language), `script-writer`, `skript-lang` and `skript-gui` (chest GUIs in Skript). Its README explains each one.

## Register a target

```ts theme={null}
import sdk from 'sdk'

sdk.scripting.registerTarget({
  id: 'skript',                       // lowercase; stored in project settings
  name: 'Skript',                     // shown in the Scripting dropdown and the code views
  folder: 'Skript',                   // plugin folder the files are written under
  language: 'plaintext',              // the code views' syntax highlighting (a Monaco id)
  reloadCommands: ['sk reload all'],  // sent to the test server after a Sync
  serverPlugin: {                     // installed on the test server when it is missing
    name: 'Skript',
    jarPrefix: 'skript',              // a jar whose file name starts with this counts as installed
    url: 'https://github.com/SkriptLang/Skript/releases/download/2.16.2/Skript-2.16.2.jar'
  },
  install: {                          // the "Export completed" modal's steps for this folder
    steps: ['Install Skript on your server.', 'Copy the `Skript` folder into `plugins`.', 'Run `/sk reload all`.']
  },
  compile(bundle, { catalog }) {
    return bundle.mechanics.map((m) => ({ path: `scripts/${m.id}.sk`, content: toSkript(m) }))
  }
})
```

`compile` returns `[{ path, content }]`, an object `{ 'path': content }`, or `{ files, warnings, errors }`. Warnings go to the app's log, and the code views show them as comments. Paths are relative to `folder`. It runs in your expansion, so you can keep it pure and test it on its own.

`serverPlugin.url` may contain `{version}` (the Minecraft version). To pick a URL in code instead, give `resolve(version)` and return the URL. No permission is needed: the user picks the target.

`install` is optional: the steps the "Export completed" modal shows for `folder` after a pack is exported, plus up to four https `links` (`{ label, url, note? }`). `{mcVersion}` in it is the project's Minecraft version. Without one, the modal shows its generic copy-and-reload steps.

`id` is lowercase letters, digits, `_` or `-`, and app-wide. `denizen` is taken by the built-in target.

## What compile receives

The **script bundle**: every mechanic and GUI in the project, as plain data. It has the same shape for every target. When an editor asks for a preview, `bundle.preview` is `true` and holds only the item being edited; leave out support files (command scripts and the like) then.

```ts theme={null}
{
  version: 1,
  projectId: 'my_project',
  contentPlugin: 'nexo',           // where the project's items go: 'nexo', 'itemsadder', ...
  preview?: true,
  commands: {
    gui: { name: 'nm', aliases: ['nexomaker'], permission: 'nm.command',
           usage: '/nm gui open <gui> [player]' }
  },
  mechanics: [ ... ],
  guis: [ ... ],
  legacy: []                       // always empty for your target; see "Legacy NMScript"
}
```

### Mechanics

```ts theme={null}
{
  id: 'greeter', itemId: 'greeter', display: 'Greeter',
  trigger: { category: 'player', event: 'joins', params: {}, nodeId: 't' },
  steps: [ ... ],                  // what runs, in order, nested
  graph: { nodes, connections },   // the raw graph, if you need positions or ids
  warnings: []
}
```

`steps` is the graph already walked. There are three kinds:

```ts theme={null}
{ kind: 'action',    command: 'Narrate', params: { message: 'Hi <player.name>' }, nodeId }
{ kind: 'condition', command: 'IsSneaking', params: {}, nodeId, then: Step[], else: Step[] }
{ kind: 'body',      command: 'Repeat', params: { count: 3 }, nodeId, body: Step[] }
```

`body` is a loop or a gate (`Repeat`, `Foreach`, `ForEachBlockInRadius`, `RandomChance`, `Cooldown`). What was wired after the card runs inside it. Params left empty in the editor are absent, so your defaults apply.

### GUIs

```ts theme={null}
{
  id: 'shop', itemId: 'shop', display: 'Shop', title: 'Shop', rows: 3,
  elements: [
    { type: 'button', id: 'buy', slot: 13, width: 1, height: 1, displayName: 'Buy', lore: [],
      actionType: 'command', command: 'say bought',   // or actionType: 'gui', targetGui: 'bank'
      ... },
    { type: 'slot', slotId: 'payment', slot: 11, returnOnClose: true },
    { type: 'text' | 'shape' | 'image', ... }          // drawn into the title glyph: nothing to do
  ],
  openCommand: '/nm gui open shop {player}',
  titleGlyph: { glyph: 'shop_glyph', shift: -38, text: '<shift:-38><glyph:shop_glyph>' },
  backgroundColor: '#c6c6c6', hideBackground: false,
  logic: { graph, triggers: [ ... ] }
}
```

* Slots count cells from 0, left to right and top to bottom. A button covers `width × height` cells from `slot`.
* `command` is one command per line, without the slash.
* `titleGlyph.text` is the title the way the content plugin writes a glyph: MiniMessage for Nexo, `:offset_N::glyph:` for ItemsAdder. The shift is already worked out. Use it as the inventory's title.
* An item slot (`type: 'slot'`) is a cell the player puts items into. If `returnOnClose` is true, give its items back when the GUI closes.

`logic.triggers` is the GUI's Logic graph, walked like a mechanic's:

```ts theme={null}
{ event: 'buttonClick', params: { button: 'buy' }, nodeId, steps: Step[] }
```

| `event` | When | `params` |
| - | - | - |
| `open` | The GUI opens | |
| `close` | It closes (before slots are given back) | |
| `buttonClick` | A button is clicked | `button`: the element's `id` |
| `slotChange` | An item slot's contents change | `slot`: the element's `slotId` |

GUI-logic steps: `takeFromSlot(slot, amount)`, `returnSlot(slot)`, `clearSlot(slot)`, `setSlot(slot, item, amount)`, `message(text)`, `giveItem(item, amount)`, `sound(sound)`, `command(command, as)` where `as` is `'server'` or `'player'`, `closeGui`, `openGui(gui)`, `wait(ticks)`. Checks: `slotHas(slot, item, amount)`, `slotEmpty(slot)`, `playerHasItem(item, amount)`, `hasPermission(permission)`. In GUI logic, `slot` is a `slotId`. Look it up in `elements`.

### The GUI command

The GUI editor shows every GUI's open command, `/nm gui open <gui> [player]` (`bundle.commands.gui`). Users copy it into their server, so your target must provide it. Denizen writes it as `nm_system.dsc`, and the Skript example writes it as `nm_system.sk`.

## The built-in vocabulary

Your target spells everything the editors offer. `catalog` (the second argument, or `sdk.scripting.catalog()`) lists it all, with labels and params:

```ts theme={null}
catalog.mechanics.triggers    // { player: { label, events: { joins: { label, targets }, ... } }, ... }
catalog.mechanics.actions     // { Narrate: { label, category, params: ['message'], targets? }, ... }
catalog.mechanics.variables   // the named variables, by category: { label, tag: '<player.name>' }
catalog.gui.triggers, catalog.gui.steps
```

Mechanics actions, by category:

| Category | Actions |
| - | - |
| Feedback (`output`) | `Narrate(message)`, `PlaySound(location, sound, pitch)`, `SendTitle(player, title, subtitle)`, `SendActionBar(player, message)`, `Toast(message)`, `Announce(message)`, `Sidebar(player, title, lines)`, `Log(message)` |
| Flow | `Run(task, definitions)`, `Wait(duration)`, `Stop`, `CancelEvent`, `Repeat(count)`, `Foreach(list)`, `ForEachBlockInRadius(center, radius, blockType)`, `RandomChance(percent)`, `Cooldown(target, id, duration)` |
| Conditionals | `IsBlock(block)`, `IsHolding(item)`, `HasPermission(permission)`, `IsSneaking`, `IsFlying`, `IsInWorld(world)`, `HasItem(item, amount)`, `IsOnGround`, `CompareValue(value, operator, expected)` |
| Data | `Flag(target, flag, value)`, `Define(variable, value)`, `Adjust(target, mechanism, value)` |
| Entities | `Spawn(entity)`, `Heal(target, amount)`, `Hurt(target, amount, cause)`, `Kill(target)`, `Equip(target, slot, item)`, `PotionEffect(target, effect, duration, amplifier)`, `RemoveEffect(target, effect)`, `Burn(target, duration)`, `Feed(player, amount)`, `Push(target, x, y, z)`, `RemoveEntity(target)`, `Mount(rider, vehicle)` |
| World | `Teleport(target, location)`, `GiveItem(player, item, amount)`, `TakeItem(player, item, amount)`, `SetHealth(target, health)`, `OpenGUI(gui, player)`, `Explode(location, power, fire, breakBlocks)`, `ModifyBlock(location, material)`, `ReplaceBlocks(center, radius, fromBlock, toBlock, percent)`, `Particle(location, effect, quantity, offset)`, `Weather(world, type)`, `SetTime(world, time)`, `Lightning(location, damage)`, `DropItem(location, item, quantity)`, `Firework(location, color, type, power)`, `WorldBorder(world, center, size)` |
| Player | `Experience(player, amount, type)`, `Kick(player, reason)`, `ClearInventory(player)`, `SetGameMode(player, mode)`, `SetFly(player, enabled)`, `Oxygen(player, amount)`, `Compass(player, location)` |
| Server | `RunCommand(command)`, `Scheme(name, location, action)` |

Triggers: `player.*` (35, from `rightclick` and `joins` to `craftItem`), `entity.*` (9), `server.*` (4) and `world.*` (10). See `catalog.mechanics.triggers` for the full list.

Spell what you can. For anything else, write a comment in the file, add a warning, and move on. Never guess. The user then sees in the log and in the code view what their target cannot do yet.

### Values and variables

Text values carry variables as tokens: `'Welcome <player.name>!'`. Every editor saves them this way, so one mapping covers both. `helpers.mapTags` rewrites the tokens you know and reports the rest:

```ts theme={null}
const { mapTags } = sdk.scripting.helpers
const TAGS = { 'player.name': 'player', 'player.location': 'location of player' }
mapTags('Hi <player.name>', (tag) => (TAGS[tag] ? `%${TAGS[tag]}%` : undefined), (tag) => warn(tag))
// -> 'Hi %player%'
```

Reference params such as `target`, `player` and `location` hold `player`, `<player>` or a token like `<context.entity>`. Item and block params hold `diamond`, `minecraft:diamond`, `DIAMOND`, or a custom item such as `nexo:ruby`. `helpers.itemRef(value)` tells them apart: `{ custom: true, id: 'ruby' }`.

### Helpers

`sdk.scripting.helpers`:

| Helper | What it does |
| - | - |
| `fill(template, params)` | `{param}` templates: `fill('send "{text}"', { text: 'Hi' })` |
| `fillLines(template, params)` | The same for a template of several lines (an array, or text with line breaks) |
| `spellingFor(entry, targetId)` | `entry.targets[targetId]`: an expansion entry's spelling |
| `valueTags(value)` | The variable tokens in a value: `['player.name']` |
| `mapTags(value, map, onUnknown)` | Rewrite variable tokens |
| `itemRef(value)` | `{ custom, id }` for an item or block id |
| `titleShift(shift, ascent)`, `glyphTitle(glyph, shift, plugin)` | How `titleGlyph` was worked out |

`sdk.scripting.program(graph)` and `sdk.scripting.guiProgram(graph)` walk a raw graph into steps, exactly as the bundle does.

## Entries other expansions add

Expansions add Mechanics triggers, actions and conditions, and GUI-logic steps and triggers. Each entry spells itself per target:

```ts theme={null}
sdk.scripting.addAction('shout', {
  label: 'Shout', params: ['text'],
  targets: { denizen: '- announce "{text}"', skript: 'broadcast "{text}"' }
})
```

When `compile` meets a command it has no table entry for, look it up in the catalog and use `spellingFor(entry, yourId)` with `fill` or `fillLines`. If there is no spelling for you, report it. To support your target in other expansions' entries, tell their authors your target id. See [Logic editors](https://docs.lodemc.net/sdk-reference.md#logic-editors) for the entry shapes.

## What the app does with your target

| | |
| - | - |
| **Export and Sync** | Your files go to `plugins/<folder>/` on the test server and to `Exports/<folder>/`. The folder is cleared and rewritten on every export. |
| **Switching targets** | When a project switches from one target to another, the files the previous target wrote are removed from the server, so the two never run the same mechanics twice. Only files the app wrote are touched. |
| **Test server** | Your `serverPlugin` is installed when the server is set up and before each start if it is missing. Your `reloadCommands` run after a Sync when the project has Mechanics or GUIs. |
| **Production packs** | The Scripting choice in the pack modal decides which target goes into the pack. |
| **Code views** | The Mechanics editor's code view and the GUI editor's Script view show your output for the item being edited, with `bundle.preview` set. |
| **Unloaded target** | If your expansion is disabled or missing, projects that chose it fall back to Denizen, with a warning in the log, rather than losing their scripts. |

## Legacy NMScript

NMScript is retired. Mechanics written by hand in NMScript before then still export through Denizen exactly as before. Your target never receives them. The export warns which items it skipped, and the editor offers to rebuild them in the graph.

## Checklist

* `compile` is pure: bundle in, files out. Test it with bundles built from real items.
* Every built-in trigger, action and condition is spelled or reported.
* Expansion entries are read through `spellingFor`.
* Variables are mapped, and the unknown ones reported.
* GUIs: inventory, buttons, item slots (given back on close), Logic, `/nm gui open`.
* Support files are left out when `bundle.preview` is set.
* `serverPlugin` and `reloadCommands` are set, and the URL names a real release file.
* The output loads on a real server. Compile a project that uses every trigger, action and check, write the files into a test server's scripts folder, and load them: zero errors is the bar.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.