Actions

Actions are executable commands that trigger when specific quest events occur. They perform operations like giving items, spawning entities, playing sounds, running commands, etc. Actions are different from Objectives: actions are things that happen, objectives are things the player must do.

When Actions Trigger

Actions can be triggered at different points in a quest's lifecycle:

In dialogues, actions can also be written as inline action strings using the format:

actionId arg1 'arg with spaces'; anotherAction arg1

Multiple actions are separated by semicolons. Arguments with spaces must be wrapped in single quotes.

Action Format

Each action in a quest's action arrays follows this JSON structure:

{
  "id": "giveitem",
  "args": ["flaxfibers", "10"]
}

• id — The action type identifier (e.g. giveitem, playsound).
• args — An array of string arguments specific to the action type.

Mega Example: All Actions in One Quest

This example shows how to combine actions across all phases of a quest. Copy it as a template for complex quests:

{
  "id": "yourmod:epic-quest",
  "cooldown": -1,
  "perPlayer": true,
  "onAcceptedActions": [
    { "id": "playsound", "args": ["game:sounds/quest-accept", "0.8"] },
    { "id": "addplayerattribute", "args": ["quest-epic-active", "true"] },
    { "id": "addjournalentry", "args": ["epic", "epic-start", "The Great Journey", "true", "You have accepted a great challenge."] },
    { "id": "spawnentities", "args": ["game:wolf-male", "game:wolf-male"] }
  ],
  "killObjectives": [
    { "validCodes": ["game:wolf-*"], "demand": 5 }
  ],
  "actionObjectives": [
    {
      "id": "reach_temple",
      "objectiveId": "reachwaypoint",
      "args": ["5120,68,5340", "5"],
      "onCompleteActions": [
        { "id": "playsound", "args": ["game:sounds/quest-step", "0.8"] },
        { "id": "notify", "args": ["yourmod:temple-reached"] }
      ]
    }
  ],
  "itemRewards": [
    { "itemCode": "game:ingot-gold", "amount": 5 }
  ],
  "actionRewards": [
    { "id": "playsound", "args": ["game:sounds/quest-complete", "1.0"] },
    { "id": "giveitem", "args": ["game:gear-rusty", "1", "Hero's Sword"] },
    { "id": "addreputation", "args": ["npc", "guild-master", "25"] },
    { "id": "addplayerattribute", "args": ["quest-epic-complete", "true"] },
    { "id": "removeplayerattribute", "args": ["quest-epic-active"] },
    { "id": "showquestfinaldialog", "args": ["yourmod:epic-title", "yourmod:epic-body", "yourmod:epic-btn1", "yourmod:epic-btn2"] },
    { "id": "spawnsmoke" },
    { "id": "despawnquestgiver", "args": ["5000"] }
  ]
}

What each phase does:

Complete Example: Dialogue Action String

In dialogues, actions are written as compact strings instead of JSON arrays:

{
  "components": [
    {
      "owner": "npc",
      "type": "text",
      "text": "npc-greeting",
      "next": "choice_01"
    },
    {
      "owner": "player",
      "type": "choice",
      "text": [
        { "text": "Accept quest", "next": "accept_step" },
        { "text": "No thanks", "next": "refuse_step" }
      ]
    },
    {
      "id": "accept_step",
      "owner": "npc",
      "type": "text",
      "text": "npc-accept",
      "actions": "acceptquest yourmod:epic-quest; playsound 'game:sounds/quest-accept' 0.8; setattribute questAccepted true"
    }
  ]
}

What the action string does:

• acceptquest yourmod:epic-quest — auto-accepts the quest
• playsound 'game:sounds/quest-accept' 0.8 — plays accept sound
• setattribute questAccepted true — sets player attribute

Commands Category

Actions that execute game commands on the server or client.

servercommand

Executes a server-side command. All arguments are joined together as the command string.

• args[0..n] — All arguments are joined to form the full command string.

{
  "id": "servercommand",
  "args": ["/weather", "set", "clear"]
}

playercommand

Executes a client-side command as the player. All arguments are joined together as the command string.

• args[0..n] — All arguments are joined to form the full command string.

{
  "id": "playercommand",
  "args": ["/emote", "wave"]
}

Core Quest Category

Actions that control quest flow, tracking, and audio feedback.

Example: Auto-Quest Chain

When a player completes Quest 1, automatically start Quest 2:

{
  "id": "yourmod:quest-1",
  "cooldown": -1,
  "perPlayer": true,
  "actionRewards": [
    { "id": "acceptquest", "args": ["yourmod:quest-2"] },
    { "id": "playsound", "args": ["game:sounds/quest-accept", "0.8"] }
  ]
}

What happens: Quest 1 completes → Quest 2 auto-accepts → sound plays.

acceptquest

Accepts a quest on behalf of the player, optionally from a specific quest giver.

• args[0] — `` The quest to accept (required).
• args[1] — `` The quest giver entity ID (optional).

completequest

Completes a quest. If no quest ID is provided, completes the current quest.

• args[0] — `` The quest to complete (optional, defaults to current quest).
• args[1] — `` The quest giver entity ID (optional).

despawnquestgiver

Despawns the quest giver entity after a delay.

• args[0] — `` Delay in milliseconds before despawning (required).

openquests

Opens the quest journal UI for the player. Takes no arguments.

trackboss

Activates boss tracking for the player. Costs 3 HP and has a 1 minute cooldown.

• args[0] — `` The boss key to track (optional).

playsound

Plays a sound effect for the player.

• args[0] — `` The sound resource location (required).
• args[1] — ` Volume level (optional, default 1.0`).

preloadbossmusic

Preloads boss music URLs so they are ready to play without delay.

• args[0] — `` First music URL to preload (required).
• args[1..n] — `` Additional music URLs (optional).

Items Category

Actions that give, take, or manipulate items in the player's inventory.

Example: Trade Quest

The player must give items to get a reward:

{
  "id": "yourmod:trade-quest",
  "cooldown": -1,
  "perPlayer": true,
  "onAcceptedActions": [
    { "id": "takeitem", "args": ["game:ingot-copper", "10"] }
  ],
  "actionRewards": [
    { "id": "questitem", "args": ["yourmod:master-key"] },
    { "id": "playsound", "args": ["game:sounds/reward", "1.0"] }
  ]
}

What happens:

• On accept: 10 copper ingots are removed from the player's inventory.
• On complete: a quest item (master-key) is given + sound plays.

takeitem

Removes items from the player's inventory.

• args[0] — `` The item code to remove (required).
• args[1] — `` Number of items to remove (required).

randomquestitem

Gives the player a random item from a loot table.

• args[0] — `` The loot table code to roll from (required).

giveitem

Gives items to the player, optionally with custom name and description via an itemizer.

• args[0] — `` The item code to give (required).
• args[1] — `` Number of items to give (required).
• args[2] — `` Custom display name for the item (optional).
• args[3..n] — `` Custom description lines (optional).

questitem / giveactionitem

Gives the player a predefined quest action item by its ID.

• args[0] — `` The action item identifier (required).

consumeactionitem

Consumes (removes) a quest action item from the player's inventory.

• args[0] — `` The action item identifier to consume (required).
• args[1] — ` Number to consume (optional, default 1`).

Journal Category

Actions that add entries to the player's journal/lore book.

addjournalentry

Adds a journal entry to the player's lore book. Supports a new format with group IDs and an older legacy format.

New format:

• args[0] — `` The journal group/category ID (required).
• args[1] — `` Unique lore entry code (required).
• args[2] — `` Display title for the entry (required).
• args[3] — `` Whether to overwrite existing entry (optional).
• args[4..n] — `` Chapter text content (at least one required).

Legacy format: Also supports a simpler format without group IDs for backward compatibility.

addvanillajournalentry

Adds a journal entry using the vanilla Vintage Story journal system.

• args[0] — `` Unique lore entry code (required).
• args[1..n] — `` Chapter text content (at least one required).

Player Category

Actions that modify player stats, attributes, and progression.

Example: Reputation Quest

Complete a quest to gain reputation and unlock a trait:

{
  "id": "yourmod:rep-quest",
  "cooldown": -1,
  "perPlayer": true,
  "actionRewards": [
    { "id": "addreputation", "args": ["npc", "guild-master", "10", "100", "rep-quest-1"] },
    { "id": "addplayerattribute", "args": ["guild-member", "true"] },
    { "id": "healplayer", "args": ["500"] },
    { "id": "notify", "args": ["yourmod:rep-gained"] }
  ]
}

What happens:

• Reputation +10 with guild-master (capped at 100, once-only key rep-quest-1).
• Player attribute guild-member set to true.
• Player healed by 500 HP.
• Notification shown.

addreputation

Adds or removes reputation with an NPC or faction.

• args[0] — ` Reputation scope: npc or faction` (required).
• args[1] — `` The NPC or faction identifier (required).
• args[2] — `` Amount to add (positive) or remove (negative) (required).
• args[3] — `` Maximum reputation cap (optional).
• args[4] — `` Key to ensure this only applies once (optional).

addplayerattribute

Sets a string attribute on the player's data.

• args[0] — `` The attribute key name (required).
• args[1] — `` The value to set (required).

addplayerint

Adds a delta to an integer player attribute.

• args[0] — `` The integer attribute key name (required).
• args[1] — `` The amount to add (required).

landclaimallowance

Sets the player's land claim allowance value.

• args[0] — `` The allowance value to set (required).

landclaimmaxareas

Sets the player's maximum number of land claim areas.

• args[0] — `` The max areas value to set (required).

removeplayerattribute

Removes a player attribute by key.

• args[0] — `` The attribute key to remove (required).

healplayer

Heals the player by a specified amount.

• args[0] — ` Amount of health to restore (optional, default 1000`).

allowcharselonce

Allows the player to re-enter character selection one time. Takes no arguments.

addtraits

Adds one or more traits to the player.

• args[0..n] — `` Trait identifiers to add (at least one required).

removetraits

Removes one or more traits from the player.

• args[0..n] — `` Trait identifiers to remove (at least one required).

Objective Helper Category

Actions that assist or reset objective tracking state.

Example: Reset Quest

A quest that can be retaken and needs its tracking state reset each time:

{
  "id": "yourmod:resettable-quest",
  "cooldown": 1,
  "perPlayer": true,
  "onAcceptedActions": [
    { "id": "resetwalkdistance", "args": ["yourmod:resettable-quest", "0"] },
    { "id": "resettimer", "args": ["yourmod:resettable-quest", "timer1"] },
    { "id": "resetexperimentalobjective", "args": ["mineblock", "yourmod:resettable-quest", "mine1"] }
  ],
  "actionObjectives": [
    {
      "id": "walk_100m",
      "objectiveId": "walkdistance",
      "args": ["yourmod:resettable-quest", "100", "0"]
    },
    {
      "id": "timer1",
      "objectiveId": "timer",
      "args": ["yourmod:resettable-quest", "timer1", "120"]
    },
    {
      "id": "mine1",
      "objectiveId": "mineblock",
      "args": ["yourmod:resettable-quest", "mine1", "game:stone-*", "20"]
    }
  ]
}

What happens:

• Every time the quest is accepted, the walk distance, timer, and mine counter are reset to zero.
• This allows the quest to be retaken without leftover progress from a previous attempt.

resetwalkdistance

Resets the walk distance counter for a walkdistance objective.

• args[0] — `` The quest containing the objective (required).
• args[1] — `` The tracking slot index (optional).

checkobjective

Forces a re-check of all objectives for the current quest. Takes no arguments.

markinteraction

Marks a coordinate as interacted for interaction-based objectives.

• args[0] — `` The coordinate to mark as interacted (required).

markentityinteraction

Marks an entity as interacted for entity interaction objectives.

• args[0] — `` The entity ID to mark (required).

resettimer

Resets a timer objective back to its starting value.

• args[0] — `` The quest containing the timer (required).
• args[1] — `` The timer objective ID (required).

resetexperimentalobjective

Resets an experimental objective's progress back to zero.

• args[0] — ` The objective type (e.g. mineblock, craftitem`) (required).
• args[1] — `` The quest containing the objective (required).
• args[2] — `` The objective ID to reset (required).

randomkill (action)

Sets up random kill slots for the randomkill objective. Assigns random entities to slots that the player must then kill.

• args[0] — `` Number of random kill slots to create (required).
• args[1] — `` Number of kills required per slot (required).
• args[2] — `` Maximum distance to search for valid mobs (required).
• args[3] — `` Localization key for the notification template (required).
• args[4] — `` Action string to run on progress (optional).
• args[5] — `` Action string to run on completion (optional).
• args[6..n] — `` Entity codes to randomly select from (at least one required).

Entity Spawning Category

Actions that spawn or recruit entities in the world.

Example: Ambush Quest

When the quest is accepted, enemies spawn and attack:

{
  "id": "yourmod:ambush-quest",
  "cooldown": -1,
  "perPlayer": true,
  "onAcceptedActions": [
    { "id": "playsound", "args": ["game:sounds/alert", "1.0"] },
    { "id": "spawnentitiesatplayer", "args": ["game:wolf-male", "game:wolf-male", "game:wolf-female"] },
    { "id": "spawnsmoke" }
  ],
  "killObjectives": [
    { "validCodes": ["game:wolf-*"], "demand": 3 }
  ]
}

What happens:

• Alert sound plays.
• 3 wolves spawn at the player's location.
• Smoke effect appears.
• Player must kill all 3 wolves.

spawnentities

Spawns one or more entities at the quest giver's location.

• args[0..n] — `` Entity codes to spawn (at least one required).

spawnentitiesatplayer

Spawns one or more entities at the player's current location.

• args[0..n] — `` Entity codes to spawn (at least one required).

spawnany

Spawns one random entity from the provided list.

• args[0..n] — `` Entity codes to randomly choose from (at least two required).

spawnsmoke

Spawns a smoke particle effect at the quest giver's location. Takes no arguments.

recruitentity

Recruits the current quest giver entity as a companion. Takes no arguments.

Entity Control Category

Actions that control existing entity behavior and state.

cycleentityanimation

Cycles through animations on an entity.

• args[0] — `` The entity code to animate (optional, defaults to quest giver).
• args[1..n] — `` Animation names to cycle through (optional).

damageentity

Deals damage to the quest giver entity.

• args[0] — ` Amount of damage to deal (optional, default 50`).

UI & Feedback Category

Actions that display UI elements, notifications, and feedback to the player.

Example: Multi-Step Notification

Show a sequence of feedback to the player:

{
  "id": "yourmod:multi-step",
  "cooldown": -1,
  "perPlayer": true,
  "actionObjectives": [
    {
      "id": "step1",
      "objectiveId": "reachwaypoint",
      "args": ["5000,70,5000", "5"],
      "onCompleteActions": [
        { "id": "notify", "args": ["yourmod:checkpoint-1"] },
        { "id": "playsound", "args": ["game:sounds/quest-step", "0.8"] }
      ]
    },
    {
      "id": "step2",
      "objectiveId": "reachwaypoint",
      "args": ["5100,70,5100", "5"],
      "onCompleteActions": [
        { "id": "notify", "args": ["yourmod:checkpoint-2"] },
        { "id": "playsound", "args": ["game:sounds/quest-step", "0.8"] }
      ]
    }
  ],
  "actionRewards": [
    { "id": "notify", "args": ["yourmod:all-done"] },
    { "id": "showquestfinaldialog", "args": ["yourmod:final-title", "yourmod:final-body"] },
    { "id": "closedialogue" }
  ]
}

What happens:

• At each checkpoint: notification + sound.
• At quest completion: final notification + dialog window + closes the dialogue.

showquiz

Opens a quiz dialog for the player.

• args[0] — `` The quiz identifier to display (required).

closedialogue

Closes the currently open dialogue window. Takes no arguments.

revealname

Reveals the true name of the quest giver NPC to the player.

• args[0] — `` Optional selector for which name to reveal (optional).

notify

Displays a notification message to the player.

• args[0] — `` The notification text to display (required).

showquestfinaldialog

Shows a final quest completion dialog with a title, text, and optional choice buttons.

• args[0] — `` Localization key for the dialog title (required).
• args[1] — `` Localization key for the dialog body text (required).
• args[2] — `` Localization key for the first button (optional).
• args[3] — `` Localization key for the second button (optional).

discover

Displays a discovery-style notification to the player (similar to discovering a new area).

• args[0] — `` The discovery message to display (required).

World Category

Actions that modify world state, blocks, and quest giver properties.

Example: Dynamic World Quest

Change the quest giver's behavior after the quest is complete:

{
  "id": "yourmod:world-change",
  "cooldown": -1,
  "perPlayer": true,
  "actionRewards": [
    { "id": "setquestgiverattribute", "args": ["friendly", "bool", "true"] },
    { "id": "setquestgiverattribute", "args": ["dialogue", "string", "npc-friendly-dialogue"] },
    { "id": "cycleentityanimation", "args": ["npc-merchant", "wave", "idle"] },
    { "id": "notify", "args": ["yourmod:merchant-now-friendly"] }
  ]
}

What happens:

• Quest giver's friendly attribute set to true.
• Quest giver's dialogue switched to a friendly one.
• Animation cycles to wave then idle.
• Notification shown.

cooldownblock

Places a cooldown on a block interaction, preventing re-use for a specified duration.

• args[0] — `` Cooldown duration in hours (required).
• args[1] — `` Block coordinate to apply cooldown to (optional, defaults to interacted block).

setquestgiverattribute

Sets an attribute on the quest giver entity.

• args[0] — `` The attribute key name (required).
• args[1] — ` The value type: bool, int, or string` (required).
• args[2] — `` The value to set (required).