skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
kaaariyaaa/scriptapiserverskill63 installs

minecraft-server-scriptapi

Guidance for working with the Minecraft Bedrock Script API @minecraft/server module. Use when answering questions about server-side scripting, world/system APIs, events, entities, components, or module versions for Minecraft Creator ScriptAPI.

How do I install this agent skill?

npx skills add https://github.com/kaaariyaaa/scriptapiserverskill --skill minecraft-server-scriptapi
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides legitimate guidance and code templates for the Minecraft Bedrock Script API. It adheres to official Microsoft documentation practices and includes standard game scripting patterns without any security risks detected.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerpass

    2 files scanned · No issues

What does this agent skill do?

Minecraft Server ScriptAPI

Workflow

  1. Scope: Identify task (events, entities, components, commands, timing). Default to latest stable version unless beta/preview requested.
  2. Docs: Navigate from module index to specific class/interface/event. Use Microsoft Learn as source of truth. Search via MCP when details missing.
  3. Output: Quote exact API names. Provide minimal working example with required imports. Verify no official equivalent exists before creating custom helpers.
    • For enums like CustomCommandParamType, always check Microsoft Learn to confirm availability.
    • @minecraft/vanilla-data is not on Microsoft Learn, so skip MCP searches for those enums.

Common patterns

Events

  • Subscribe/unsubscribe on world/system events. Guard logic for performance.

Dimensions

  • Use world.getDimension(MinecraftDimensionTypes.<Dimension>) and pick the appropriate dimension for the task.

Components

  • Check existence before access.
  • Use typed IDs: EntityComponentTypes, BlockComponentTypes, ItemComponentTypes.

Scheduling

  • Use system.run, system.runTimeout, system.runInterval, system.runJob.

Identifiers

  • MUST use @minecraft/vanilla-data enums: MinecraftBlockTypes, MinecraftEntityTypes, MinecraftItemTypes, MinecraftDimensionTypes, MinecraftEffectTypes, potionEffect, potionDelivery, feature, enchantment, cooldownCategory, cameraPresets, biome.
  • Custom IDs: Must include namespace prefix (e.g., example:cmd). One consistent prefix per addon.

Example:

import { world, system } from "@minecraft/server";
import { MinecraftDimensionTypes, MinecraftBlockTypes } from "@minecraft/vanilla-data";

system.runInterval(() => {
  const dimensions = [MinecraftDimensionTypes.Overworld, MinecraftDimensionTypes.Nether];
  const blocks = [MinecraftBlockTypes.Stone, MinecraftBlockTypes.Sand, MinecraftBlockTypes.GrassBlock];
  for (const dimension of dimensions) {
    for (const block of blocks) {
      world.getDimension(dimension).setBlockType({ x: 0, y: 0, z: 0 }, block);
    }
  }
});

Permission modes

Read-only

  • Before simulation/events/tick start. No world mutations.
  • Fix: defer to system.run/runTimeout/runJob.

Doc verification

  • When using any method/property, always check Microsoft Learn to confirm whether it is read-only safe or early-execution safe.
  • Look for explicit notes in the API reference (read-only / early-execution) and follow them strictly.
  • For arrow-function callbacks only, also check for restricted-execution notes like:
    • "This closure is called with restricted-execution privilege."
    • "This function can't be called in restricted-execution mode."
  • If a restricted-execution note applies, review the arrow-function body to ensure no read-only or early-execution violations; defer with system.run if needed.

Example (read-only deferral):

world.beforeEvents.playerInteractWithBlock.subscribe((event) => {
  const player = event.player;
  system.run(() => {
    player.runCommand("say ok");
  });
});

Early-execution

  • Before world loads. Many APIs unavailable.
  • Fix: defer to world.afterEvents.worldLoad or system.run.
  • Subscribe at root to avoid missing events.

Safe in early-execution:

  • Event subscriptions (world/system beforeEvents/afterEvents)
  • system.clearJob, clearRun, run, runInterval, runJob, runTimeout, waitTicks
  • BlockComponentRegistry.registerCustomComponent, ItemComponentRegistry.registerCustomComponent

Custom commands

  • Interface: CustomCommand (name, description, permissionLevel, mandatoryParameters, optionalParameters).
  • Parameters: CustomCommandParameter (name, type, optional enumName).
  • Param types and arrow-function argument types:
    • String -> String
    • PlayerSelector -> Player
    • Location -> Vector3
    • ItemType -> ItemType
    • Integer -> Number
    • Float -> Number
    • Enum -> String
    • EntityType -> EntityType
    • EntitySelector -> Entity
    • Boolean -> Bool
    • BlockType -> BlockType
  • Register enums: CustomCommandRegistry.registerEnum(name, values).
  • Register cmd: CustomCommandRegistry.registerCommand(customCommand, callback).
  • Callback: (origin, ...args) => CustomCommandResult.
  • Custom command callbacks run with restricted-execution privileges, so do not call read-only-restricted methods directly; defer with system.run if needed.
  • When using an arrow function, align parameter names and order with the CustomCommandParameter.name list; avoid mismatched names or generic args when parameters are defined.

Example:

import {
  system,
  StartupEvent,
  CommandPermissionLevel,
  CustomCommandParamType,
  CustomCommandStatus,
} from "@minecraft/server";

system.beforeEvents.startup.subscribe((init: StartupEvent) => {
  init.customCommandRegistry.registerEnum("example:mode", ["on", "off"]);

  init.customCommandRegistry.registerCommand(
    {
      name: "example:demo",
      description: "Command demo",
      permissionLevel: CommandPermissionLevel.GameDirectors,
      cheatsRequired: true,
      mandatoryParameters: [
        {  type: CustomCommandParamType.String, name: "msg", },
        {  type: CustomCommandParamType.Enum, name: "example:mode"},
      ],
      optionalParameters: [
        { type: CustomCommandParamType.Boolean, name: "silent" },
        { type: CustomCommandParamType.Integer, name: "count" },
      ],
    },
    (origin, msg, mode, silent, count) => {
      const msgValue = String(msg ?? "ok");
      const modeValue = String(mode ?? "off");
      const silentValue = Boolean(silent ?? false);
      const countValue = Number(count ?? 1);

      return {
        status: CustomCommandStatus.Success,
        message: silentValue
          ? undefined
          : `[${origin.sourceType}] ${msgValue} mode=${modeValue} count=${countValue}`,
      };
    }
  );
});

Script events

  • Send: system.sendScriptEvent(id, message) (namespaced ID, payload string).
  • Receive: system.afterEvents.scriptEventReceive.subscribe(callback, options?).
  • Event: ScriptEventCommandMessageAfterEvent (id, message, sourceType, optional sourceEntity/sourceBlock/initiator).
  • Filter: ScriptEventMessageFilterOptions.namespaces.

Example:

import { system, world, ScriptEventSource } from "@minecraft/server";

system.afterEvents.scriptEventReceive.subscribe((event) => {
  const { id, message, sourceType, initiator, sourceEntity, sourceBlock } = event;
  if (id !== "example:say") return;

  switch (sourceType) {
    case ScriptEventSource.Block:
      world.sendMessage(`sendBy:${sourceBlock?.typeId ?? "unknown"} ${message}`);
      break;
    case ScriptEventSource.Entity:
      world.sendMessage(`sendBy:${sourceEntity?.typeId ?? "unknown"} ${message}`);
      break;
    case ScriptEventSource.NPCDialogue:
      world.sendMessage(`sendBy:${initiator?.typeId ?? "unknown"} ${message}`);
      break;
    case ScriptEventSource.Server:
      world.sendMessage(`sendBy:server ${message}`);
      break;
  }
});

Performance

  • Expensive work in events: use system.runJob(generator) to spread across ticks.
  • Short-circuit before iterating large sets.

system.run variants

  • run: next tick.
  • runTimeout(cb, ticks): delay N ticks. 0 can cause tight loops if misused.
  • runInterval(cb, ticks): repeat every N ticks until clearRun.
  • runJob(generator): long-running work. Keep iterations small.

Type safety

  • Use typeId checks and verify component existence.
  • instanceof only for documented @minecraft/server classes.

Minimal templates

Event subscription:

world.afterEvents.playerJoin.subscribe((event) => {
  const player = event.player;
});

Tick loop:

system.runInterval(() => {
  // tick logic
}, 1);

Get dimension:

const overworld = world.getDimension(MinecraftDimensionTypes.Overworld);

Spawn entity:

const overworld = world.getDimension(MinecraftDimensionTypes.Overworld);
overworld.spawnEntity(MinecraftEntityTypes.Zombie, { x: 0, y: 80, z: 0 });

Give item:

const item = new ItemStack(MinecraftItemTypes.Diamond, 1);
player.getComponent("inventory")?.container?.addItem(item);

Apply effect:

player.addEffect(MinecraftEffectTypes.Speed, 200, { amplifier: 1 });

Get component (typed):

const health = entity.getComponent(EntityComponentTypes.Health);

Pitfalls

  • Null components: Check existence before access.
  • Heavy events: Use system.runJob.
  • Permissions: Avoid read-only/early-execution violations.
  • Raw IDs: Use typed enums.
  • Namespaces: One consistent prefix per addon.

MCP tools

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/kaaariyaaa/scriptapiserverskill/minecraft-server-scriptapi">View minecraft-server-scriptapi on skillZs</a>