Sandkit

• hookId: "item:use"
• callback(args, context)
  • args.itemId
  • args.useId
  • args.kind: "instant" | "sustained" | "chargeThenFire"
  • args.baseline (read-only)
  • args.prepared (mutable)
  • context.cancel()
  • context.cancelled
• options.itemIds
• options.priority

const unsubscribe = api.hooks.intercept(
  "item:use",
  (args, context) => {
    args.prepared.energyCost = Number(args.baseline.energyCost) * 2;

    if (args.prepared.energyCost > 1000) {
      context.cancel();
    }
  },
  { itemIds: ["laser"], priority: 0 },
);

• hookId: "teleport:effect:create"
• callback(args, context)
• options (optional)
• Deprecated alias: "teleport:effect"

api.hooks.intercept("teleport:effect:create", (args, context) => {
  context.cancel();
});

• hookId: "action:start"
• callback(args, context)
• options (optional)
• Deprecated alias: "action:intercept"

api.hooks.intercept("action:start", (args, context) => {
  if (args.action?.id === "example") context.cancel();
});

• hookId: "input:keyDown"
• callback(args, context)
• options (optional)
• Deprecated alias: "input:keydown"

api.hooks.intercept("input:keyDown", (args, context) => {
  if (args.code === "KeyK") context.cancel();
});

• hookId: "input:keyUp"
• callback(args, context)
• options (optional)
• Deprecated alias: "input:keyup"

api.hooks.intercept("input:keyUp", (args, context) => {
  if (args.code === "KeyK") context.cancel();
});

• hookId: "placePoints:suppress"
• callback(args, context)
• options (optional)
• Deprecated alias: "placePoints:isSuppressed"

api.hooks.intercept("placePoints:suppress", (args, context) => {
  if (args.type === "exampleStructure") context.cancel();
});

• hookId: "placePoints:directionalArrows:suppress"
• callback(args, context)
• options (optional)
• Deprecated alias: "placePoints:directionalArrows:isSuppressed"

api.hooks.intercept(
  "placePoints:directionalArrows:suppress",
  (args, context) => {
    if (args.type === "exampleStructure") context.cancel();
  },
);

• hookId: "entity:update"
• callback(args, context)
  • args.entityTypeId (read-only)
  • args.entity (mutable)
  • args.deltaTimeSeconds (read-only)
  • args.phase (read-only): "normal" | "capturing" | "launching"
  • args.isVisible (read-only)
  • args.playerWorldX (read-only)
  • args.playerWorldY (read-only)
  • args.worldMinX (read-only)
  • args.worldMinY (read-only)
  • args.worldMaxX (read-only)
  • args.worldMaxY (read-only)
  • args.cellSize (read-only)
  • args.timeSeconds (read-only)
  • context.cancel()
  • context.cancelled
• options.entityTypes
• options.priority

const unsubscribe = api.hooks.intercept(
  "entity:update",
  (args) => {
    if (args.phase !== "normal") return;
    args.entity.targetX = args.playerWorldX;
    args.entity.targetY = args.playerWorldY;
  },
  { entityTypes: ["lumling"], priority: 0 },
);

• hookId: "building:place"
• callback(args, context)
• args.structureId
• args.x
• args.y
• args.data
• options.structureTypes (optional)
• options.priority (optional)

api.hooks.intercept("building:place", (args, context) => {
  if (args.structureId === "exampleStructure") context.cancel();
});

• hookId: "building:clearShape"
• callback(args, context)
• args.structure
• options (optional)

api.hooks.intercept("building:clearShape", (args, context) => {
  if (args.structure.data?.protected) context.cancel();
});

• hookId: "input:scroll"
• callback(args, context)
• args.deltaY
• options (optional)

api.hooks.intercept("input:scroll", (args, context) => {
  if (args.deltaY !== 0) context.cancel();
});

• hookId: "input:boostDown"
• callback(args, context)
• options (optional)
• Deprecated alias: "input:boost-down"

api.hooks.intercept("input:boostDown", (args, context) => {
  context.cancel();
});

• hookId: "input:descendDown"
• callback(args, context)
• options (optional)
• Deprecated alias: "input:descend-down"

api.hooks.intercept("input:descendDown", (args, context) => {
  context.cancel();
});

• hookId: "input:escape"
• callback(args, context)
• options (optional)

api.hooks.intercept("input:escape", (args, context) => {
  context.cancel();
});

• hookId: "interactable:suppressHover"
• callback(args, context)
• args.type
• args.structure
• options (optional)

api.hooks.intercept("interactable:suppressHover", (args, context) => {
  if (args.type === "exampleStructure") context.cancel();
});

• hookId: "fire:element:ignite"
• callback(args, context)
• args.x
• args.y
• args.elementType
• options (optional)

api.hooks.intercept("fire:element:ignite", (args, context) => {
  if (args.elementType === exampleElementType) context.cancel();
});

• hookId: "projectile:fire:overStructure"
• callback(args, context)
• args.projectile
• args.x
• args.y
• options.projectileTypes (optional)
• options.priority (optional)

api.hooks.intercept(
  "projectile:fire:overStructure",
  (args, context) => {
    if (args.projectile.type === "exampleProjectile") context.cancel();
  },
);

• hookId: "projectile:hit"
• callback(args, context)
• args.projectile
• args.travelResult
• options.projectileTypes (optional)
• options.priority (optional)

api.hooks.intercept("projectile:hit", (args, context) => {
  if (args.projectile.type === "exampleProjectile") context.cancel();
});

• hookId: "player:position:commit"
• callback(args, context)
• args.previousWorldX
• args.previousWorldY
• args.proposedWorldX
• args.proposedWorldY
• args.velocityX
• args.velocityY
• options (optional)

api.hooks.intercept("player:position:commit", (args) => {
  args.velocityX *= 0.5;
  args.velocityY *= 0.5;
});

• hookId: "progression:purchase"
• callback(args, context)
• args.domain: "tech" | "upgrade"
• args.id
• args.itemId (optional)
• args.costs
• options (optional)

api.hooks.intercept("progression:purchase", (args, context) => {
  if (args.id === "exampleTech") context.cancel();
});

• hookId: "excavation:prepare"
• callback(args)
  • args.sourceId (read-only)
  • args.sourceKind (read-only): "tool" | "projectile" | "structure" | "drone"
  • args.originCellX (read-only)
  • args.originCellY (read-only)
  • args.consumedVoid (read-only)
  • args.profileId (mutable)
  • args.patternDiameterCells (mutable)
  • args.drillTierDamage (mutable)
• options.priority

const unsubscribe = api.hooks.modify(
  "excavation:prepare",
  (args) => {
    if (args.sourceId !== "implosionGun") return;

    args.profileId = "example:voidGun";
    args.patternDiameterCells = 21;
    args.drillTierDamage = 8;
  },
  { priority: 0 },
);

• hookId: "locator:scan:prepare"
• callback(args)
  • args.originWorldX (read-only)
  • args.originWorldY (read-only)
  • args.hasTarget (mutable)
  • args.targetCellX (mutable)
  • args.targetCellY (mutable)
  • args.outerTint (mutable): [R, G, B]
  • args.innerTint (mutable): [R, G, B]
  • args.noTargetToast (mutable)
  • args.noTargetToastKey (mutable)
  • args.triangulationLensOverride: true | false | null (null is standard behavior)
• options.priority

const unsubscribe = api.hooks.modify(
  "locator:scan:prepare",
  (args) => {
    const target = findNearestTarget(args.originWorldX, args.originWorldY);
    args.hasTarget = target !== null;

    if (!target) {
      args.noTargetToast = "No example target was found.";
      args.noTargetToastKey = "mods|example|noTarget";
      return;
    }

    args.targetCellX = target.cellX;
    args.targetCellY = target.cellY;
    args.outerTint[0] = 103;
    args.outerTint[1] = 232;
    args.outerTint[2] = 249;
    args.triangulationLensOverride = true;
  },
  { priority: 0 },
);

• hookId: "vacuum:prepare"
• callback(args)
  • args.nozzleCellX (read-only)
  • args.nozzleCellY (read-only)
  • args.targetCellX (mutable)
  • args.targetCellY (mutable)
  • args.pattern (mutable)
• options.priority

const vacuumPattern = [
  [0, 1, 0],
  [1, 1, 1],
  [0, 1, 0],
];

const unsubscribe = api.hooks.modify(
  "vacuum:prepare",
  (args) => {
    const target = api.input.getMousePositionAtCell();
    args.targetCellX = target.x;
    args.targetCellY = target.y;
    args.pattern = vacuumPattern;
  },
  { priority: 0 },
);

• hookId: "vacuum:element:prepare"
• callback(args)
  • args.elementType (read-only)
  • args.matterType (read-only)
  • args.isTransportable (read-only)
  • args.collectable (mutable)
  • args.visibleInPicker (mutable)
• options.priority

const unsubscribe = api.hooks.modify(
  "vacuum:element:prepare",
  (args) => {
    if (args.matterType !== sandkit.enums.MatterType.Liquid) return;

    args.collectable = true;
    args.visibleInPicker = true;
  },
  { priority: 0 },
);

• hookId: "player:movement:prepare"
• callback(args)
• options (optional)
• Deprecated alias: "player:movement"

api.hooks.modify("player:movement:prepare", (args) => {
  args.horizontalMaxSpeed *= 1.25;
});

• hookId: "building:placementLimit:prepare"
• callback(args)
• options (optional)
• Deprecated alias: "building:placementLimit"
• Deprecated alias: "building:placement-limit"

api.hooks.modify("building:placementLimit:prepare", (args) => {
  args.maxCount = args.maxCount === null ? 10 : args.maxCount + 10;
});

• hookId: "fluxEmanator:processing:prepare"
• callback(args)
• options (optional)
• Deprecated alias: "fluxEmanator:processing"
• Deprecated alias: "flux-emanator:processing"

api.hooks.modify("fluxEmanator:processing:prepare", (args) => {
  args.speedMultiplier *= 2;
});

• hookId: "render:pipes:prepare"
• callback(args)
• options (optional)
• Deprecated alias: "render:pipes"

api.hooks.modify("render:pipes:prepare", (args) => {
  args.layer = "foreground";
});

• hookId: "structures:moved:prepare"
• callback(args)
• args.moved
• args.failedToPlace
• options (optional)

api.hooks.modify("structures:moved:prepare", (args) => {
  prepareMovedStructures(args.moved, args.failedToPlace);
});

• hookId: "structures:removed:prepare"
• callback(args)
• args.removed
• args.structures (optional)
• args.byMove
• options (optional)

api.hooks.modify("structures:removed:prepare", (args) => {
  prepareRemovedStructures(args.removed, args.byMove);
});

• hookId: "weapon:reload:prepare"
• callback(args)
• args.weaponId
• args.reloadMs
• args.maxAmmo
• options.weaponIds (optional)
• options.priority (optional)

api.hooks.modify("weapon:reload:prepare", (args) => {
  args.reloadMs *= 0.8;
}, { weaponIds: ["exampleWeapon"] });

• hookId: "projectile:travel:prepare"
• callback(args)
• args.projectileType
• args.firstCollisionStep
• args.maxCollisionSteps
• args.collidesWithTerrain
• args.collidesWithStructures
• options.projectileTypes (optional)
• options.priority (optional)

api.hooks.modify("projectile:travel:prepare", (args) => {
  args.collidesWithStructures = false;
}, { projectileTypes: ["exampleProjectile"] });

• hookId: "projectile:impact:prepare"
• callback(args)
• args.projectileType
• args.impactKind
• args.profileId
• args.power
• args.centerPower
• args.radiusCells
• options.projectileTypes (optional)
• options.priority (optional)
• Deprecated alias: args.radius

api.hooks.modify("projectile:impact:prepare", (args) => {
  args.radiusCells = 8;
}, { projectileTypes: ["exampleProjectile"] });

• hookId: "player:collision:prepare"
• callback(args)
• args.phaseThroughTerrain
• args.phaseThroughStructures
• args.maxStepCells
• options (optional)

api.hooks.modify("player:collision:prepare", (args) => {
  args.maxStepCells = 4;
});

• hookId: "trigger:schedule:prepare"
• callback(args)
• args.triggerId
• args.intervalMs
• args.sequentialRuns
• options.triggerIds (optional)
• options.priority (optional)

api.hooks.modify("trigger:schedule:prepare", (args) => {
  args.intervalMs *= 0.5;
}, { triggerIds: ["pump"] });

• hookId: "progression:cost:prepare"
• callback(args)
• args.domain: "tech" | "upgrade"
• args.id
• args.itemId (optional)
• args.currencyId
• args.amount
• options (optional)

api.hooks.modify("progression:cost:prepare", (args) => {
  if (args.currencyId === "gold") args.amount *= 0.9;
});

• hookId: "resource:collection:prepare"
• callback(args)
• args.resourceId
• args.sourceKind
• args.cellX
• args.cellY
• args.amount
• args.feedback: "default" | "silent"
• options.resourceIds (optional)
• options.priority (optional)

api.hooks.modify("resource:collection:prepare", (args) => {
  args.amount *= 2;
}, { resourceIds: ["fluxite"] });

• hookId: "resource:delivery:prepare"
• callback(args)
• args.resourceId
• args.sourceKind
• args.sourceId
• args.sourceCellX
• args.sourceCellY
• args.targetCellX
• args.targetCellY
• args.mode: "world" | "collection"
• args.amount
• args.feedback: "default" | "silent"
• options.resourceIds (optional)
• options.priority (optional)

api.hooks.modify("resource:delivery:prepare", (args) => {
  args.mode = "collection";
}, { resourceIds: ["fluxite"] });

• hookId: "resource:balance:prepare"
• args.resourceId (read-only)
• args.balance

api.hooks.modify("resource:balance:prepare", (args) => {
  args.balance += api.storage.get("example", "gold") ?? 0;
}, { resourceIds: ["gold"] });

• hookId: "gold:removal:prepare"
• args.requestedAmount (read-only)
• args.shortfall

api.hooks.modify("gold:removal:prepare", (args) => {
  const banked = api.storage.get("example", "gold") ?? 0;
  args.shortfall = Math.max(0, args.shortfall - banked);
});

• hookId: "gold:removal:settle"
• args.requestedAmount, args.physicalRemoved (read-only)
• args.shortfall

api.hooks.modify("gold:removal:settle", (args) => {
  const banked = api.storage.get("example", "gold") ?? 0;
  const covered = Math.min(banked, args.shortfall);
  api.storage.set("example", "gold", banked - covered);
  args.shortfall -= covered;
});

• eventId: "item:used"
• callback(payload)
  • payload.itemId
  • payload.useId
  • payload.kind
  • payload.cellX
  • payload.cellY
  • payload.prepared (read-only)

const unsubscribe = api.events.on("item:used", (payload) => {
  if (payload.itemId !== "laser") return;

  spawnSparklesAtCell(payload.cellX, payload.cellY);
});

• eventId: "frame:render"
• callback(payload)

api.events.on("frame:render", () => {
  drawOverlay();
});

• eventId: "scene:game:started"
• callback(payload)
• Deprecated alias: "scene:started:game"

api.events.on("scene:game:started", () => {
  initializeGameScene();
});

• eventId: "earlyAccess:completed"
• callback(payload)
• Deprecated alias: "earlyAccess:complete"

api.events.on("earlyAccess:completed", (payload) => {
  onEarlyAccessCompleted(payload);
});

• eventId: "terrain:destroyed"
• callback(payload)
• payload.cellX
• payload.cellY
• payload.cellType
• Deprecated alias: payload.x and payload.y

api.events.on("terrain:destroyed", (payload) => {
  onTerrainDestroyed(payload.cellX, payload.cellY, payload.cellType);
});

• eventId: "fog:cellRevealed"
• callback(payload)
• payload.cellX
• payload.cellY
• Deprecated alias: payload.x and payload.y

api.events.on("fog:cellRevealed", (payload) => {
  onFogCellRevealed(payload.cellX, payload.cellY);
});

• eventId: "upgrade:levelSelected"
• callback(payload)
  • payload.itemId
  • payload.upgradeId
  • payload.level

api.events.on("upgrade:levelSelected", (payload) => {
  onLevelSelected(payload.itemId, payload.upgradeId, payload.level);
});

• eventId: "building:placed"
• callback(payload)
• payload.structure
• payload.x
• payload.y
• payload.isBatch
• payload.isCopied

api.events.on("building:placed", (payload) => {
  onBuildingPlaced(payload.structure, payload.x, payload.y);
});

• eventId: "building:removed"
• callback(payload)
• payload.structureId
• payload.x
• payload.y
• payload.isBatch

api.events.on("building:removed", (payload) => {
  onBuildingRemoved(payload.structureId, payload.x, payload.y);
});

• eventId: "structures:placed"
• callback(payload)
• payload.structures

api.events.on("structures:placed", (payload) => {
  onStructuresPlaced(payload.structures);
});

• eventId: "structures:removed"
• callback(payload)
• payload.removed
• payload.structures (optional)
• payload.byMove

api.events.on("structures:removed", (payload) => {
  onStructuresRemoved(payload.removed, payload.byMove);
});

• eventId: "structures:moved"
• callback(payload)
• payload.moved
• payload.failedToPlace

api.events.on("structures:moved", (payload) => {
  onStructuresMoved(payload.moved, payload.failedToPlace);
});

• eventId: "game:ready"
• callback(payload)

api.events.on("game:ready", () => {
  initializeExample();
});

• eventId: "game:started"
• callback(payload)

api.events.on("game:started", () => {
  startExample();
});

• eventId: "tutorial:stepChanged"
• callback(payload)
• payload.step

api.events.on("tutorial:stepChanged", (payload) => {
  onTutorialStepChanged(payload.step);
});

• eventId: "tutorial:completed"
• callback(payload)
• payload.skipped

api.events.on("tutorial:completed", (payload) => {
  onTutorialCompleted(payload.skipped);
});

• eventId: "tech:unlocked"
• callback(payload)
• payload.techId
• payload.suppressMusic

api.events.on("tech:unlocked", (payload) => {
  onTechUnlocked(payload.techId, payload.suppressMusic);
});

• eventId: "worldItem:pickedUp"
• callback(payload)
• payload.worldItemId
• payload.type

api.events.on("worldItem:pickedUp", (payload) => {
  onPickup(payload.worldItemId, payload.type);
});

• eventId: "resource:collected"
• callback(payload)
• payload.resourceId
• payload.amount
• payload.sourceKind
• payload.cellX
• payload.cellY

api.events.on("resource:collected", (payload) => {
  onResourceCollected(payload.resourceId, payload.amount);
});

• options.placement?: "raised" | "docked"
  • Not a fan of this naming but "docked" puts it right on top of the hotbar (between it and panels such as Filter Config) while "raised" puts it above those panels. Let me know ifyou can think of a better naming scheme.
• options.order?
• options.render()
• Deprecated alias: api.ui.overlays.register(slot, overlayId, render)

const mountHandle = api.ui.regions.mount(
  "hotbar",
  "extra-actions",
  {
    placement: "docked",
    order: 0,
    render: () => sandkit.react.createElement(ExtraActions),
  },
);

mountHandle.update({
  order: 10,
  render: () => sandkit.react.createElement(UpdatedActions),
});

• wrapper(Original, props)

const overrideHandle = api.ui.overrides.register(
  "resources",
  (Original) => sandkit.react.createElement(
    sandkit.react.Fragment,
    null,
    sandkit.react.createElement(Original),
    sandkit.react.createElement(ResourceAddon),
  ),
);

• options.bankOffset
• options.minimumBankCount?

const source = api.ui.hotbar.createBankSource({
  bankOffset: 1,
  minimumBankCount: 2,
});

const hotbar = api.ui.hotbar.useHotbar();
console.log(
  hotbar.bankCount,
  hotbar.activeBankIndex,
  hotbar.activeSlotIndex,
);

• props.source
• props.slotIndex
• props.action
• props.keyLabel?
• props.active?
• props.onSelect?
• props.onClear?

const slot = sandkit.react.createElement(
  api.ui.components.ActionSlot,
  { source, slotIndex: 0, keyLabel: "1" },
);

• props.title?
• props.children
• props.className?
• props.style?

const panel = sandkit.react.createElement(
  api.ui.components.Panel,
  { title: "Options" },
  "Panel content",
);

• props.children
• props.active?
• props.border?: true | false
• props.disabled?
• props.small?
• props.variant?: "primary" | "danger"
• props.className?
• props.style?
• props.onClick?

const button = sandkit.react.createElement(
  api.ui.components.Button,
  { onClick: openPanel },
  "Open",
);

const focusable = api.ui.navigation.useFocusable({
  id: "example-button",
  scope: "example-scope",
  onActivate: openExample,
});

api.ui.navigation.useFocusScope({
  id: "example-scope",
  active: true,
  priority: 10,
});

• Deprecated alias: controllerFocusClass(focused)

tooltipHover: {
  type: "custom",
  dataFieldMessage: {
    message: "Mode {mode}; channel {channel}.",
    messageKey: "mods|example|machineTooltip",
    fields: [
      {
        param: "mode",
        field: "mode",
        valueLabels: { input: "Receiving", output: "Sending" },
        valueKeys: {
          input: "mods|example|receiving",
          output: "mods|example|sending",
        },
      },
      { param: "channel", field: "channel", fallback: 1, round: true },
    ],
  },
}

• definition.structureType
• definition.intervalMs
• definition.process
• Deprecated alias: api.structures.addProcessor(structureId, definition)

api.structures.processing.register(
  "exampleStructure:process",
  {
    structureType: "exampleStructure",
    intervalMs: 250,
    process: (structure, context) => {
      const empty = context.isCellEmptyAtCell(
        structure.x,
        structure.y,
      );
    },
  },
);

• Deprecated alias: isEnabledAt(cellX, cellY)

• Deprecated alias: setEnabledAt(cellX, cellY, enabled)

• eventId: "element:moved"
• callback(payload)
• options.guard.elementType (required)

api.events.on(
  "element:moved",
  (payload) => handleElementMoved(payload),
  { guard: { elementType } },
);

• eventId: "terrain:updated"
• callback(payload)
• options.guard.terrainType (required)
• Deprecated alias: "terrain:update"

api.events.on(
  "terrain:updated",
  (payload) => {
    handleTerrainUpdate(payload);
  },
  { guard: { terrainType } },
);

• eventId: "worker:update:post"
• callback(payload)
• Deprecated alias: "update:post"

api.events.on("worker:update:post", (payload) => {
  runPostUpdate(payload);
});

• hookId: "cell:process"
• callback(args, context)
• options.guard.elementType (required)
• options.priority (optional)

api.hooks.intercept("cell:process", handleCell, {
  guard: { elementType },
});

• hookId: "element:update"
• callback(args, context)
• options.guard.elementType (required)
• options.priority (optional)

api.hooks.intercept("element:update", handleUpdate, {
  guard: { elementType },
});

• hookId: "element:move"
• callback(args, context)
• options (optional)

api.hooks.intercept("element:move", (args, context) => {
  handleElementMove(args, context);
});

• hookId: "element:move:blocked"
• callback(args, context)
• options.guard.elementType (required)
• Deprecated alias: "element:blocked"

api.hooks.intercept(
  "element:move:blocked",
  (args, context) => {
    handleBlockedMovement(args, context);
  },
  { guard: { elementType } },
);

• hookId: "element:duration:expire"
• callback(args, context)
• options.guard.elementType (required)
• Deprecated alias: "element:duration"

api.hooks.intercept(
  "element:duration:expire",
  (args, context) => {
    handleDurationExpiry(args, context);
  },
  { guard: { elementType } },
);

• hookId: "fire:element:burn"
• callback(args, context)
• options (optional)

api.hooks.intercept("fire:element:burn", (args, context) => {
  handleElementBurn(args, context);
});

• hookId: "shaker:elementOn"
• callback(args, context)
• options (optional)

api.hooks.intercept("shaker:elementOn", (args, context) => {
  handleShakerElement(args, context);
});